Using Oracle Commerce

F59937-04
October 2023
Using Oracle Commerce,

F59937-04

Copyright © 1997, 2023, Oracle and/or its affiliates.

This software and related documentation are provided under a license agreement containing restrictions on
use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your
license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,
transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse
engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is
prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If
you find any errors, please report them to us in writing.

If this is software, software documentation, data (as defined in the Federal Acquisition Regulation), or related
documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S.
Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated software,
any programs embedded, installed, or activated on delivered hardware, and modifications of such programs)
and Oracle computer documentation or other Oracle data delivered to or accessed by U.S. Government end
users are "commercial computer software," "commercial computer software documentation," or "limited rights
data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental
regulations. As such, the use, reproduction, duplication, release, display, disclosure, modification, preparation
of derivative works, and/or adaptation of i) Oracle programs (including any operating system, integrated
software, any programs embedded, installed, or activated on delivered hardware, and modifications of such
programs), ii) Oracle computer documentation and/or iii) other Oracle data, is subject to the rights and
limitations specified in the license contained in the applicable contract. The terms governing the U.S.
Government's use of Oracle cloud services are defined by the applicable contract for such services. No other
rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications.
It is not developed or intended for use in any inherently dangerous applications, including applications that
may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you
shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its
safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this
software or hardware in dangerous applications.

Oracle®, Java, and MySQL are registered trademarks of Oracle and/or its affiliates. Other names may be
trademarks of their respective owners.

Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are
used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Epyc,
and the AMD logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered
trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products,
and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly
disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise
set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be
responsible for any loss, costs, or damages incurred due to your access to or use of third-party content,
products, or services, except as set forth in an applicable agreement between you and Oracle.
Contents

1 Understand Oracle Commerce

Product features 1-1

2 First Steps
Subscribe to Oracle Commerce 2-1
Prepare for store development 2-2
Become familiar with the administration interface 2-3

3 Work with the Dashboard

View reports 3-2
Find documentation and training videos 3-2
Enter basic store information 3-3

4 Design Your Store Layout

Access layouts 4-1
Understand the default layouts 4-1
Create a new layout instance (cloning) 4-2
Customize your store layouts 4-3
Customize layout components 4-3
Work with layout components 4-4
Customize slots 4-7
Customize stacks 4-10
Modify your page layout settings 4-14
Upgrade deployed widgets 4-17
Work with role-based layouts 4-18
Preview your store 4-19

5 Customize Your Store’s Design Theme

Understand the default theme 5-1

iii
 Create a new theme (cloning) 5-1
Customize your theme 5-2
Modify theme code 5-4
Apply a theme to a site 5-5
Delete a theme 5-5

6 Modify Your Storefront Using Code Editing Tools

Modify a component’s code 6-1
Modify the theme CSS style sheet 6-2
Use developer tools to customize your store 6-2

7 Manage Your Catalog

Understand catalogs 7-1
Work with independent catalogs 7-2
Work with filtered catalogs 7-4
Work with legacy catalogs 7-8
Create legacy catalogs 7-9
Associate catalogs with sites or accounts 7-11
Edit catalog items without publishing 7-11
Create and edit product types 7-14
Create and work with products 7-23
Find products in catalogs 7-24
Create and work with SKUs 7-26
Create add-on products 7-30
Organize products in collections 7-32
Configure catalogs with optional collections 7-37
Link and unlink collections and products 7-39
Create default parent collections 7-41
Create custom properties for collections 7-44
Add metadata to products and collections 7-47
Display related products 7-48
Configure AI Recommendations Rules 7-49
Work with the Recommendations API 7-55
Display product recommendations 7-61
Add images to products 7-63
Create gift cards 7-65
Manage inventory 7-66
Preview your changes 7-68

iv
8 Manage SEO
Configure URL patterns 8-1
Customize SEO tags 8-5
Manage SEO content 8-7
Understand canonical tags 8-9
Utilize widgets for SEO 8-10
Understand SEO snapshots 8-12
Configure URL redirects 8-13
Edit the [Link] file 8-14
Customize structured data 8-16
Understand XML sitemaps 8-17
Understand SEO localization 8-18
Control access to storefront servers 8-19

9 Manage Search Settings

Understand index fields 9-1
View index fields 9-1
Understand the searchable field ranking list 9-2
Add fields to the searchable field ranking list 9-3
Edit the searchable field ranking list 9-4
Understand the thesaurus 9-5
Create and edit thesaurus entries 9-6
Understand keyword redirects 9-8
Create and edit keyword redirects 9-9
Refine and order search results 9-11
Multiple sites and search 9-14
Configure dynamic content 9-14
Use the search REST APIs 9-16

10 Manage Media for Your Store

View the media library 10-1
Upload media files 10-2
Edit and remove media files 10-3
Import image assignments 10-4

11 Import and Export Catalog Items and Inventory

Understand export guidelines 11-1
Export catalog items 11-2

v
 Import catalog items and inventory 11-5

12 Manage Promotions
Understand promotions 12-1
Understand promotion targets 12-2
Understand currency-specific promotions 12-3
Understand audience-specific promotions 12-3
Understand site-specific promotions 12-4
Copy an existing promotion 12-4
Create an order discount promotion 12-5
Create an item discount promotion 12-6
Create a buy one get one promotion 12-8
Create a shipping discount promotion 12-9
Create a gift with purchase promotion 12-10
Define a promotion 12-11
Enable and disable promotions 12-19
Organize promotions in folders 12-19
Include or exclude products, SKUs, or collections 12-21
Exclude promotions 12-23
Add a coupon code to a promotion 12-24
Manage promotions with stacking rules 12-26
Manage upsell messages 12-27

13 Define Audiences
Understand audience definitions 13-1
View the list of audiences 13-12
Create an audience 13-12
Update an audience 13-14
Copy an existing audience 13-14
Disable an audience 13-15
Delete an audience 13-16
View audience usage 13-16
Add personalization to headless applications 13-16

14 Configure Tax Processing

Understand tax processor integrations 14-1
Understand the Tax Code property 14-2
Configure the AvaTax integration 14-2
Configure the Vertex O Series integration 14-3

vi
 Integrate with an external tax processor 14-4
Configure Ship from Warehouse Locations 14-5
Disable all tax processors 14-6

15 Add personalization to headless applications

16 Configure Payment Processing

Configure payment settings 16-1
Configure the CyberSource integration 16-2
Configure the PayPal integration 16-4
Configure the Chase Paymentech integration 16-5

17 Configure Shopper Settings

Configure the password policy 17-1
Configure the logged-in shopper session 17-2
Configure guest checkout 17-3
Disable soft login 17-3
Configure account-based shoppers 17-3
Configure shopper registration 17-4

18 Configure Email Settings

Enable the types of email your store sends 18-1
Configure Abandoned Cart settings 18-5
Ensure emails are not rejected as spam 18-6
Configure an Alternate SMTP Email Relay 18-6

19 Configure Internal User Accounts

Understand role-based access control 19-1
View role contents 19-8
Create new user profiles 19-8
Edit user profiles 19-9
Deactivate and reactivate user profiles 19-11
Access the Commerce administration interface 19-11

vii
20 Configure Shipping
Create shipping regions 20-1
Create a shipping method 20-1
Specify a fallback shipping method 20-3
Specify a default shipping country 20-4
Configure shipping surcharges 20-4
Understand externally priced shipping methods 20-5

21 Configure Wish Lists

Understand wish list features 21-1
Implement wish lists 21-4
Configure Facebook access and announcements 21-4
Enable wish list email settings 21-4
Edit wish list widget content 21-6
Set up wish lists in a multiple site environment 21-7
Configure wish lists for OSF applications 21-8

22 Localize Your Store

Understand store localization 22-1
Select additional languages 22-2
Prepare your catalog for translation 22-4
Import translations for catalog items 22-4
Manually translate properties 22-4
Translate store text 22-5
Configure the default locale for a site 22-5
Create items in the default locale of a site 22-6
Use a specific locale code in a REST request 22-6
Troubleshoot translation issues 22-6

23 Configure Price Groups

Understand price groups 23-1
Create and edit price groups 23-3
Manually add prices to products and SKUs 23-5
Import prices for products and SKUs 23-5
Activate price groups 23-6
Update prices without publishing 23-7
Work with price group inheritance 23-8

viii
24 Use Volume Pricing for Products
Understand volume pricing 24-1
Add volume prices to a product 24-1
Display volume pricing in a storefront 24-2
Understand volume price display in a product listing 24-3
Understand volume price display on the Product Layout 24-4

25 Publish Changes
Understand publishing 25-1
Understand worksets 25-3
Save changes to worksets 25-4
Create and edit worksets 25-4
Schedule publishing 25-6
Publish changes using the REST API 25-7

26 Configure Business Accounts

Understand accounts, contacts, and contracts 26-1
Understand delegated administration 26-2
Work with accounts 26-2
Work with account addresses 26-8
Work with account contacts 26-10
Work with account contracts 26-15
Understand shoppers and new account registration requests 26-16
Submit new account registration information as a business shopper 26-17
Work with account registration requests 26-18
Work with registration requests to review, change status, approve, and reject requests 26-21
Understand contact registration requests 26-23
Submit new contact registration information 26-24
Understand working with contact registration requests 26-25
Work with contact requests to review, change status, approve, and reject 26-31
Delete contact information 26-33

27 Create Page Layouts that Support Different Types of Shoppers

Understand the different types of shopper 27-1
Create cloned layouts 27-2
Restrict guest checkout 27-2
Manage pages for account-based shoppers 27-3
Configure page layouts for account hierarchies 27-4

ix
 Manage page layouts to support account and contact registration requests 27-5

28 Use Order Approvals

Understand order approvals 28-1
Enable or disable order approvals 28-2
Understand the purchase limit for order approvals 28-3
Set a price hold period 28-3
Manage approvers for an account 28-4
Understand how approvers approve and reject orders 28-5
Understand the effect of order approvals on scheduled orders 28-5
Notify users of order approval-related events 28-6

29 Run Multiple Stores from One Commerce Instance

Understand what is shared among sites 29-1
Define a site 29-2
View, preview, and publish sites 29-3

30 Accessibility Tasks
About keyboard shortcuts 30-1

31 Secure Your Service

Understand security features 31-1
Perform security tasks 31-3

A Appendix: Layout Widgets and Elements

Account Addresses A-1
Account Contacts A-1
Account Details A-1
Address Book A-2
Add Product to Wish List A-2
Assets A-2
Asset Details A-2
Breadcrumb A-2
Cart Shipping A-3
Cart Summary A-3
Category Content A-3
Checkout Schedule Orders A-3

x
Collection A-4
Collection Navigation A-4
Collection Navigation Basic A-4
Content Item A-4
Customer Address A-4
Checkout Address Book A-5
Customer Profile A-5
CyberSource Payment Authorization A-5
Footer A-5
Guided Navigation A-6
Gift Card A-6
Header A-6
Hero A-7
Login/Registration Checkout A-7
Loyalty Details A-7
Loyalty Payment A-8
Managed Account Address Book A-8
No Search Results A-8
Notifications A-8
Order Approvals A-8
Order Approval Settings A-9
Order Confirmation A-9
Order Confirmation Summary A-9
Order Confirmation with Additional Info A-9
Order Details A-10
Order Details with Additional Info A-10
Order History A-10
Order Summary A-11
Order Summary Checkout A-11
Orders Pending Approval A-11
Overlayed Guided Navigation A-11
Page Not Found A-11
Pay After Approval A-12
Payment Details A-12
Payment Methods (Formerly Split Payments Widget) A-12
Payment Gateway Options A-12
Product Details A-13
Product Listing A-13
Product Recommendations A-14
Product Social Meta Tags A-15
Product Quick View A-15

xi
Promotion A-15
Purchase Lists A-16
Purchase List Details A-16
Quick Order A-16
Quote Details A-17
Related Products A-17
Return Items A-17
Return Item Details A-18
Request Quote A-18
Review Order A-18
Scheduled Order A-18
Scheduled Order List A-18
Scheduled Order - Checkout A-19
Search Results A-19
Shopping Cart A-19
Split Payments A-19
Update Password A-19
Web Content A-20
Wish List Canvas A-20
Wish List Content A-20
Wish List Header A-21
Wish List Invitation A-21
Wish List Notification Settings A-21
Wish List Settings Header A-22
Wish List Welcome A-22

xii
1
Understand Oracle Commerce
Oracle Commerce is a scalable, flexible eCommerce solution designed specifically to run in
the Oracle Cloud. The service provides the infrastructure and tools necessary to build a
highly customizable, feature-rich storefront for your business.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Commerce comprises the following core pieces:

• The Commerce administration interface, which you use to design and manage your store.
You access it through the URL given to you by Oracle when you subscribe to the service.
The URL is similar to the following:
<[Link]>/occs-admin/#
• Your storefront, located at the URL Oracle provides. Initially you are provided with a test
version of the site, which you modify through the administration interface to create your
own store.
• The Agent Console, which your customer service representatives can use to assist
shoppers with their orders. The Agent Console is typically located at
<[Link]>/occs-agent/#. The Agent Console is described in
Understand the Agent Console.
Note: Oracle supplies you with three separate environments as part of your subscription:
testing (also called development), staging, and production. The URLs for the three
components shown above vary for each environment.
Commerce also provides the following pieces:
• Developer features for extending the capabilities of your store, including a set of REST
APIs and tools for customizing widgets. See Understand Extension Features, Understand
the Open Storefront Framework and Create a Widget .
• Integrations with third-party vendors (for example, tax calculation services and payment
processors) and other Oracle Cloud services. For more information on the integrations
available, refer to the Oracle Help Center page for Commerce.

Product features
This section lists some of the key capabilities that are available with or supported by
Commerce and indicates where you can find more information about them.
With Commerce, you can perform the following operations related to managing an
eCommerce storefront:
• Customize the templates and layouts that determine how your store looks. See Design
Your Store Layout.
• Manage your catalogs, inventory, and pricing. See Manage Your Catalog and Configure
Price Groups.

1-1
 Chapter 1
Product features

• Translate your catalogs and content into different languages and display prices in
locale-appropriate currencies. See Localize Your Store.
• Provide advanced search tools for your site. See Manage Search Settings.
• Manage your Search Engine Optimization (SEO) strategy. See Manage SEO
Settings.
• Offer discounts and promotions. See Manage Promotions.
• Personalize storefront content for different shoppers. See Define Audiences.
• Support a loyalty points program. See Work with Loyalty Programs.
• Offer product recommendations and display related products. See Display product
recommendations and Display related products.
• Manage transactional emails between the store and your shoppers. See Configure
Email Settings.
• Support wish lists with links to social networks. See Configure Wish Lists.
• Integrate with payment and tax processors. See Configure Payment Processing
and Configure Tax Processing.
• View reports about your store. See Understand Your Reports.

Business-to-Consumer and Business-to-Business Commerce

Commerce supports both business-to-consumer (B2C, sometimes referred to as retail)
and business-to-business (B2B) models. In B2C, your store sells to individual
shoppers. In B2B, your store sells to buyers who represent another company or
organization.
B2B features are not enabled by default in your environment. Note that B2B is referred
to as “account-based commerce” in the Commerce documentation.
For more information, see Configure Business Accounts.

Running multiple stores

You can manage more than one storefront from a single subscription to Commerce.
Certain elements, for example shopper profiles, can be shared among your sites. For
more information, refer to Run Multiple Stores from One Commerce Instance.

1-2
2
First Steps
Before you can start developing your store, there are some preparatory steps you must
perform, including activating the service, reviewing the initial materials provided by Oracle,
and becoming familiar with the web-based administration interface for Oracle Commerce.
This section provides information on these steps.

Subscribe to Oracle Commerce

Before you can start using Commerce, you must purchase a subscription.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

For information on how to do so, please contact an Oracle sales representative: http://
[Link]/us/corporate/contact/[Link]
After purchasing your subscription, you will receive an email asking you to activate the
service by confirming your order. Once your service has been activated, you will receive
additional emails so you can set up your Oracle Cloud account.
When you purchase a Commerce subscription, you are also provided tenancy in the Oracle
Cloud Infrastructure (OCI), which allows you to provision and maintain your Commerce
environment and access your contracted environments. You will also receive additional
information with links to extensive resources to help you get started.

Create a new Cloud account

Once you get the email from Oracle, click on the Create new cloud account button provided
within the email. This obtains your order information an creates an account for you and takes
you to the New Cloud Account Information page. This page allows you to provide the
information to create an account, as well as identify your Subscription Order Number and
Subscripation ID.
1. Provide the information requested on the page. This includes your name, email and a
password that allows you to access the console.
2. Provide a Tenancy Name, which is used to identify your environment whenever you sign
into the Console. This name is shared with your cloud account. This name can be
changed later if you wish.
3. Identify the Home Region where your account will be created. Once you have created
your tenancy, this cannot be changed.
4. Once you have provided all of the information, click Create Tenancy.
Once you have created an account, you will receive an email that guides you on getting
started with your account.

2-1
 Chapter 2
Prepare for store development

Configure your environment

When you receive the email that you account has been generated, clcik the Sign In
button to access your account and configure your environment.
1. The Oracle Cloud Account Sign In screen appears. This displays the Tenancy and
Identity Domain you are signing in to. Enter the User Name and The Oracle Cloud
Application Portal screen appears.
2. By clicking on the Overview link, the Overview page displays your service details
and information about your environment.
3. Click on the Environments tab to select the compartment. Compartments are a
collection of related resources that can be accessed by specific groups that have
been provided with the correct permissions. For detailed information on
compartments, refer to Learn Best Practices for Setting Up Your Tenancy. Once
you have selected the compartment, click Create to create the environment.
4. The Create Environment screen displays, where you provide the environment
name, the type of instance and an administrator email. Provide a name for your
environment. Select the Oracle Commerce Cloud Service instance type and
add your administrator's email address. Ensure that your Region is set correctly.
Clicking on Show Advanced Options displays the compartments you have
configured.
5. Click Create to generate your new environment.
Once you have created your environment, you can see the Commerce CLoud
Environment Details page which shows detailed environment and status information
about your environment.
For detailed information on working with the Oracle Cloud Infrastrcture, refer to the
Oracle Cloud Infrastructure documentation.

Prepare for store development

The materials you receive from Oracle after you subscribe to the service include
detailed information about preparing for store development.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

It is important to review these materials carefully with your Oracle representative and
complete any required preliminary tasks to ensure your implementation goes as
smoothly as possible. In addition, it is suggested that you review the product
documentation and become familiar with the key concepts of the Commerce
administration interface.
You can access the latest product documentation and training videos through the
Oracle Help Center. The Commerce page also contains links to blogs, developer
communities, and Support. (Please note that some of these resources require an
account for access.)
The administration interface also provides direct links to the documentation and videos
as described in Work with the Dashboard.
Important: Commerce is designed to provide your shoppers with a fast, responsive
storefront. However, it is critical to consider site performance from the beginning of

2-2
 Chapter 2
Become familiar with the administration interface

your implementation project and build performance testing into your development strategy as
early as possible. It is highly recommended that your site developers read Improve
Performance before starting any customization work.

Become familiar with the administration interface

The Commerce administration interface (sometimes referred to as the Admin UI) is a web-
based application you use to perform many of the tasks required to set up and maintain your
storefront.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You access it at the URL provided to you by Oracle after you subscribe to the service. The
URL typically takes the following form:
<[Link]>/occs-admin/#

For initial development, you use the administration interface running in your test environment.
As part of setting up your service, Oracle configures an administrator account that allows a
designated person at your organization to log in and start creating accounts for other users
as needed. The materials you receive from Oracle after you subscribe to the service include
instructions on how the designated administrator can complete the login fields for the first
time. For more information, refer to Access the Commerce administration interface.

2-3
3
Work with the Dashboard
The dashboard is the first page you see after you log into Oracle Commerce. It allows you to
navigate to the different functional areas of the administration interface.
The dashboard is shown in the image below.

Use the icons in the left pane to navigate to the functional areas described below.
• Catalog: Manage products and SKUs.
• Marketing: Create promotions and target content to specific audiences.
• Design: Change the layout and other design elements of your store.
• Media: Manage your catalog images.
• Search: Manage your store’s catalog search features.
• Accounts: Create and manage accounts and contacts for a store that is used for
account-based commerce. Note that these features may not be available in your
environment.
• Settings: Configure other features your store supports, for example shopper profiles and
emails.

3-1
 Chapter 3
View reports

• Reports: View report data for your store.

• Service Operations: View messages about webhook status (webhooks are used
to transmit data related to store activities. For more information, see Use
Webhooks).
• Publishing: Push new content and other changes to your storefront.
If options you are expecting to see do not appear, the role assigned to your profile may
not have access to them. Refer to Understand Role-based Access Control for more
information.
The dropdown list in the main area of the page shows the name of the store you are
working on (in the illustration, Commerce Site). If you have set up more than one
store, you can use the dropdown list to switch to a different store. See Run Multiple
Stores from One Commerce Cloud Instance.
The dashboard also contains the following elements:
• Reports for orders, gross revenue, and site visits over the last seven days. The
data applies to store whose name is showing at the top of the report display.
• The most recent Commerce blog posts.
• Links to documentation and training videos.
• The Commerce version running in your environment.

View reports
The dashboard automatically displays a snapshot of report data for orders, gross
revenue, and site visits.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The data applies to the store whose name is showing at the top of the display. Click
the arrow under any report to switch the view. Click View Full Report to display the
report on the Reports page.
You can access more reports through the Reports icon.
For more information, see Understand Your Reports.

Find documentation and training videos

You can access product documentation and training videos from the administration
interface dashboard.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Click How Do I? to view the documentation or click Videos and Tutorials to view a list
of available training videos.
You can also access the product documentation and videos through the Oracle Help
Center.

3-2
 Chapter 3
Enter basic store information

Enter basic store information

You must enter basic information about your store before you perform any other setup steps.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

In some cases, you will not be able to change basic store information after you enter it.
To enter the basic information for your store:
1. Log into the administration interface at the URL provided to you by Oracle. Typically you
would use the administration interface in your test environment for this task. (See
Become familiar with the administration interface.)
2. Click the Settings icon.
3. Select Setup.
4. If your Commerce instance runs multiple sites (stores), pick a site to configure from the
list that appears above the settings list. See Run Multiple Stores from One Commerce
Instance for more information.
5. Click the General tab.
6. In the Site Title field, enter the value you want to use for the HTML <title> tag of your
store’s home page. This value is typically used by search engines as the title that
appears for your store in a list of search results. It is also visible to shoppers in a number
of places, for example in browser tabs, and it is offered to them as the default text for
bookmarks.
7. In the Site Base URL field, enter your production store’s base URL. You do not need to
include the protocol (HTTP or HTTPS) in the URL. If you do, it will be stripped off when
you save the settings. The actual protocol used will always be HTTPS, regardless of what
you specify. So, for example, if you enter [Link] in the Site Base
URL field, the actual base URL for the site is [Link] See
Understand the site base URL for more information.
8. On the Location tab, fill in the following fields:
• Default Time Zone
• Site Time Zone
• Store Default Language
• Additional Store Languages
• Reporting Currency
Important: Do not change your store’s default language once you set it, especially if you
have already created catalog items such as products, SKUs, and collections. See
Localize Your Store for more information.
You do not have to select a default language for the administration interface. The
administration interface automatically displays in your browser’s preferred language,
provided it is a language that Oracle Commerce supports. See Languages supported by
the storefront for more information.
Once you add additional store languages, a Content Language dropdown appears at the
top of the administration interface, next to the Preview button. Use this dropdown to
select an additional language when you translate your store text.

3-3
 Chapter 3
Enter basic store information

9. On the URL Patterns tab, customize the URL pattern for your store’s product and
collection pages. See Configure URL patterns for more information.

Understand the site base URL

Each site running on your Commerce instance must have a different base URL. The
site base URL setting is used as the prefix for all of the site’s URLs. For example, if a
site’s base URL is [Link] the URL for a specific
product might be [Link]
prod10002.

If your Commerce instance runs multiple sites, there are several strategies available
for using site base URLs to distinguish between sites:
• Use unique domain names. For example, [Link] and
[Link].
• Use unique top-level domains. In particular, country-code top-level domains are
often used to distinguish country stores. For example, [Link]
and [Link].
• Use unique subdomains. For example, [Link] and
[Link], or [Link] and
[Link].
• Use unique pathnames. This approach uses context roots (subdirectories) to
distinguish sites. For example, [Link]/shoes and
[Link]/gloves, or [Link]/fr and
[Link]/it.
If your site uses the subdirectory structure for the base URL, and a shopper with items
in their cart switches from one site to another site with the same base URL, if those
items are available for sale on the site they switch to, those particular items will remain
in the cart. Any items not available for sale on the site the shopper switches to will be
removed from the cart.

Define additional store settings

As described in the previous section, the Setup page contains some required values
you must specify before you start development on your store. The page also contains
some general settings that are optional or can be specified later in the development
process. These additional settings are described below.
• Favicon: Optional. Select an image to use as the favorite or shortcut icon for your
site’s pages. Browsers display this image in a number of places, for example in a
bookmark list.
• No-Image Image: Optional. Select the default image to use for any product if no
other image is available.
• Theme: Optional. Select a theme for this site. If your Commerce instance includes
multiple sites, you can select a different theme for each site. See Run Multiple
Stores from One Commerce Instance for more information about creating and
configuring multiple sites. See Customize Your Store’s Design Theme for more
information about themes.
• Default catalog: Optional. If you create multiple catalogs, select a default catalog
for the site. By default, the value of this setting is the default catalog, called
Product Catalog. For more information, see Manage Your Catalog.

3-4
 Chapter 3
Enter basic store information

• Make Default Site: Optional. If your Commerce instance includes multiple sites, select
the Make Default Site checkbox to make the current site the default. See Run Multiple
Stores from One Commerce Instance for more information about creating and configuring
multiple sites.
• Location tab: Default Price Group and Additional Price Groups (optional).
Oracle Commerce uses price groups to manage and display prices in different currencies.
Your Oracle Commerce instance comes with one configured price group, whose currency is
US Dollars. If you want to display prices in other currencies, you must create new price
groups, one for each currency. See Configure Price Groups for more information.
Important: Price groups you add to the Additional Price Groups field can be seen and
selected by all shoppers who visit your store. If your store uses account-based commerce, do
not select price groups that are associated with accounts in the Additional Price Groups
field. Prices associated with specific accounts should be seen only by logged-in contacts from
those accounts. See Configure Business Accounts for more information.

3-5
4
Design Your Store Layout
Your storefront is made up of layouts, which represent the different page types that can
appear, such as product details, checkout, and order confirmation. The default layouts act as
templates, and you use them to design, adjust, and preview your pages before publishing
live.
Layouts contain a set of design tools, known as widgets, that define the structure of your web
store pages. Several widgets are themselves made up of configurable sub-component
elements. Widgets contain within them the specific UI functionality to which they relate. For
example, the Order Confirmation layout contains information on items ordered, prices,
shipping address, and so on. Each layout’s widgets combine to form the overall page layout.
Accessible via a component library, widgets can be added, removed, cloned, and customized.
Note: You can use an extension to upload custom widgets and widget elements to your store.
See Understand Extension Features for more details.

Access layouts
To access layouts, click the Design icon on the dashboard. The default Layout tab is
displayed.

This section applies to Storefront Classic only.

You will see overviews of the layout page types on the Layout tab. To avoid excessive
scrolling, use the Filter icon, or Sort drop down, to access your preferred layout. In addition
to the selection filters, you can choose whether or not to display layouts for accounts, and
you can search for a specific layout by entering details in to a Filter layouts box.
The layout configuration menu icons displayed on the right of your layout overview enable
you to customize each of the layouts. Here you can access the Layout Settings, Clone
Layout, Grid View, and Preview configuration menus.

Understand the default layouts

A flag icon next to a layout name indicates the default layout instance for any given layout
type. The default layout is used if no other layout is assigned based on the page contents.

This section applies to Storefront Classic only.

Opening the Layout tab displays overviews of the layout page types available in Commerce.
Note: Non-default layout instances may not be visible to shoppers with the exception of the
Article, Product Details, and Collections layouts assigned to selected products, product types
or collections. This is also dependent on the shopper’s chosen viewport.
Each time you clone a layout instance, you have the option to make that newly-cloned layout
the default.

4-1
 Chapter 4
Create a new layout instance (cloning)

Create a new layout instance (cloning)

You can create a new layout instance by cloning an existing layout instance; this action
makes a copy of the original.

This section applies to Storefront Classic only.

When creating the newly-cloned layout you can configure settings such as sites,
notes, viewports, default settings, and SEO information. To do so, complete the
following steps:
1. Click the Design icon, and click the Layout tab.
2. Navigate to the layout you want to clone by either searching by name, or filtering
by layout, site, or viewport.
3. Highlight the layout overview, and click the Clone Layout option from the
configuration toolbar.
The New Layout dialog screen is displayed.
4. Enter the newly-cloned layout’s name and any related notes. See Customize your
store layouts for more details.
Note: Within the Collections layout you can assign the newly-cloned layout to a
collection. Collections represent groups of products which have similar properties,
such as, women’s dresses or men’s shoes. You should also note that within the
Product layout you can assign the newly-cloned layout to a product type or
product.
To select a collection, product type, or product, begin by typing or pasting some
text in the relevant text box within the Layout Assignment section. The filter
matches letters or numbers that you type, wherever they appear in the name, not
just at the beginning. Usually, as you type more characters, there are fewer
matches. You can assign a layout to more than one collection. As products and
collections are made available from all catalogs, you must ensure you have
assigned the catalog that is relevant for your site.
5. (Optional) Configure the new layout with one of the following checkbox options:
• Make Default Layout - defines the new layout as the default. This layout is
rendered for anonymous shoppers and registered shoppers.
• Display Layout to Account Shoppers Only - restricts the new layout to
account-based shoppers only.
You can enable these settings when designing a set of layouts for your
anonymous and registered shoppers, and another set for your account-based
shoppers. See Create Page Layouts that Support Different Types of Shoppers for
more details.
6. Enter all other settings, such as the preferred Site, Viewport, Page Title, Page
Address, Cart Preview, Layout Preview, and any new metadata tag information.
7. Click Save to confirm all settings. You can preview your newly cloned layout by
clicking the Layout Preview icon.

4-2
 Chapter 4
Customize your store layouts

Customize your store layouts

You can use the layout configuration toolbar options to customize the design of your web
store pages.

This section applies to Storefront Classic only.

The toolbar is accessed on the right hand side of any layout overview, visible as a row of
icons. The same configuration options are also available above any layout opened via Grid
View, within which the Layout Preview also provides access.
You can also use custom widgets and elements to extend the functionality of your web store.
See Understand widgets for more details. This may be especially useful for developers
working on implementations of Oracle Commerce. This guide also provides you with a
general summary of each of the widgets and elements. See Appendix: Layout Widgets and
Elements.

Customize layout components

Layouts have access to a set of components in the form of widgets, slots, application
JavaScript, and stacks, displayed within a component library. .

This section applies to Storefront Classic only.

Before designing your store pages, you can choose which of these are visible, and which are
hidden from view. Those which are visible are consequently available for use in the relevant
layouts.
By default, the Quote Details and Request Quote widgets are automatically hidden. You will
need to unhide these widgets if you are enabling quoting functionality on your web store.
Note: Choosing to hide components already in use has no impact on those particular
instances.
To customize layout components:
1. Click the Design icon and display the Components tab.
2. Filter which component types are displayed by using the Type or Source filters. You can
also search for a specific component by entering details in to a Filter box.
An overview list of components displays. It includes the component type, the number of
instances, and the latest version number.
3. (Optional) A green arrow next to the overview information indicates that an update is
available for that particular component. Click the arrow to update the component to the
latest version. If an update is not available, then a green check mark is displayed.
4. (Optional) To view all hidden components, click the Show Hidden Components button
next to the filters - the eye icon overlaid with a strikethrough line indicates the hidden
status.
5. (Optional) To view all unhidden components, which are the components that are available
for use in layouts, click the Do Not Show Hidden eye icon button next to the filters.
6. Highlight your preferred component.

4-3
 Chapter 4
Work with layout components

7. To hide your highlighted component from the component library, click the eye icon.
Doing so means that this particular component will not be available within the
Components menu of any associated layouts.
Note: Any existing instances will remain in use.
8. To unhide your highlighted component from view, click the eye icon overlaid with a
strikethrough line. This is now available for use in layouts.
9. Click the component name to expand the component’s details. From here you can
select the following elements:
• Extend JavaScript button: Opens a JavaScript file for a widget, which you
can edit and save. This JavaScript will be applied to all instances of the
widget. The Extend JavaScript button is visible for non-extension widgets. For
more information on this feature, see Use the JavaScript Code Layering User
Interface feature.
Note: The widget JavaScript is only editable for custom widgets that have had
their editable JavaScript property activated.
• Go To Widget Code icon: Displays the coding options page. See Modify a
component’s code for more details.
• Widget Settings icon: Opens the configuration options available for that
particular widget.
• Download Source icon: Downloads the widget file for each widget instance.
• Applies to all Sites check box: Ensures settings are applied across all sites,
when running multiple instances of Oracle Commerce. This option applies only
in the case of a global widget or an application JavaScript component.

Work with layout components

Each layout has an associated component library that provides access to a group of
layout-specific widgets and/or elements and stacks.

This section applies to Storefront Classic only.

Choose your preferred layout from the Layout tab, and select the Grid View
configuration option to display it in a structured grid. Accessible via an expandable
menu at the bottom of the screen, the Components menu’s widgets and stacks can be
dragged to the layout’s grid and rearranged as required.
Within Grid View you can access each individual widget’s settings via the Layout
Settings icon. Here you can name the widget or add related internal notes which do
not appear on your live store. Several widgets also contain a configurable Settings
menu as well as a Layout menu where the widget’s elements can be customized.
Note: When adding multiple collections to the Collections layout, you may see an error
displayed if the collection IDs exceed the maximum field length of 255 characters. In
order to avoid this limitation, you can clone the layout, and add any additional
collections to the new identical layout.
Widget and stack settings can include the following menu tabs:
• Layout - provides access to sub-component elements.
• Settings - provides access to the general widget configurations.

4-4
 Chapter 4
Work with layout components

• About - provides general information including the widget instance version and an
indication of whether the latest version is in use. See Upgrade deployed widgets for more
details. Clicking the Go to Widget Code button within the About tab takes you directly to
that widget’s code.
Add widgets to a layout
To add widgets to a layout:
1. Click the Design icon and display the Layout tab.
2. Using the Home Layout as an example, select the Home Layout default instance, and
click the Grid View icon. This is where the structure of your page is defined.
3. Locate the relevant section of the grid where you want to add a new instance of a widget
and click to highlight an existing region.
4. The new widget instance can be added above, below, or as part of the selected region’s
location.
5. Click the highlighted region’s row header to display the toolkit.

6. Create a new row above , or below , your current selection.

OR
Use the cursor selection arrows on either side of the region’s edges to re-size it into a
new position within the existing region.
Note: The Grid View region defaults to a maximum width of 12 columns. When a Grid
View row contains more than one region, the combined column width must total 12.
7. Open the Components section at the bottom of your screen to select a widget type.
8. Select the widget type and drag it to the new row, or within an existing row if relevant.
When dragging a widget instance from the component library to your page layout, you
are prompted to create a new version of that widget. If the widget already exists on the
page layout, then you can also clone the widget to create another copy.
9. Click Create New Widget Instance to confirm.
OR
Click the Clone Widget icon to the right of the widget name.
10. Name the new widget instance, and click Save to confirm.

Rearrange/remove widgets in a layout

Locate the row region containing the widget you want to rearrange, or remove, within your
chosen layout’s Grid View section.
To rearrange widgets, drag them to rows, between rows or alongside other widgets within a
row.
Note: Rows consist of 12 columns and can be resized into a number of region widths that
total 12 by dragging the cursor selection arrows at the edges of the row. You can also click
the Adjust Widths icon from the row header to open the Region Widths dialog and enter the
row columns manually.
To remove a widget, highlight it and click the ‘x’ icon. You will see a message confirming
you’ve removed that particular widget instance. Once the widget has been removed, you can
then delete that entire row by highlighting it and clicking the trash can icon.
Rearrange/remove elements

4-5
 Chapter 4
Work with layout components

Several widgets contain elements which you can add, rearrange, and remove to
achieve the look you want for your chosen widget.
Elements are the sub-component parts that make up the overall widget structure. They
can be accessed via an element library within several of the widgets’ settings:
To access the elements:
1. Click the Design icon and display the Layout tab.
2. Highlight your preferred layout instance and open using the Grid View icon.
Note: When you have multiple instances of layouts, using the search box to filter
for your preferred layout may avoid excessive scrolling.
3. Double click the relevant widget to open. You can also open by clicking the
Settings icon located on the top right corner of each widget.
A new window opens displaying a combination of the Layout, Settings, and About
menus, depending on which widget you have opened.
Note: The About menu contained in each of the widget settings enables you to go
directly to that widget’s code by clicking the Go to Widget Code button.
4. Click the Layout option to display the elements.
5. Open the Element Library section at the bottom of your screen to select an
element
6. Drag and drop your chosen element. You can resize and rearrange elements,
depending on where you want them to be displayed in the widget. Clicking the row
header will open the Row Controls options where you can add rows above or
below the current row. You can also adjust the widths of the regions and you can
also remove elements using the trash can or the individual element ‘x’ icon.
7. Save your choices and preview, or cancel to keep the existing panel layout.
Configure image elements and company logo
You can add images to your storefront via the Image element, including your company
logo. Access to the element is provided via any widget that contains an Element
Library.
To configure an image element, or company logo:
1. Click the Design icon and display the Layout tab.
2. Use the filter options to locate your preferred layout instance, and click the Grid
View icon.
Note: When you have multiple instances of layouts, using the search box to filter
for your preferred layout may avoid excessive scrolling.
3. Highlight your preferred widget, or, in the case of configuring your company logo,
highlight the Header widget. You can also add a new widget, rather than using pre-
loaded widgets.
4. Double click the widget to open. Clicking the Settings icon located on the top right
corner of each widget will also open it.
A new window opens displaying a combination of the Layout, Settings, and About
menus, depending on which widget you have opened.
Note: The About menu contained in each of the widget settings enables you to go
directly to that widget’s code by clicking the Go to Widget Code button.
5. Click the Layout option to display the elements.

4-6
 Chapter 4
Customize slots

6. (Optional) Delete the Logo element if you wish to upload your company logo.
Note: When adding your company logo, you must delete the pre-loaded logo element
and replace it with a logo image.
7. Open the Element Library section at the bottom of your screen.
8. Drag the Image element to the row.
9. Click the Image element title to open the configuration options page.
10. Configure the image element by naming it, selecting where to retrieve the image from,
entering a hyperlink which is navigated to via the image, and adjusting the appearance
settings.
11. Click Done to save and exit.

Customize slots
Slots provide a means of content variation similar to stacks, however, only a single variant of
a slot will be returned to the visitor’s browser based on server-side rules.
Configure audience-based content slots
You can create several versions of your store content in order to reach a variety of target
audiences. For example, content images may be based on gender, or age, categories.
To do so, you can add a Content Variation Slot to any layout.
To configure audience-based content:
1. Click the Design icon and display the Layout tab.
2. Navigate to any layout by using the filter options.
3. Select your preferred layout and click the Grid View icon.
4. Locate the relevant section where you would like to place a Content Variation Slot and
highlight an existing region.
5. Either:
Select an existing region and ensure all widgets are removed so that just the region itself
remains.
Or
Add a new row (which contains regions) above or below using the arrows on the row
menu bar.
6. See Work with layout components for details on adjusting a region’s width settings, and
removing widgets.
7. Open the Components menu, select Content Variation Slot and drag to the empty
region. You will see a control (or default) variant, and an unassigned variant.
8. Drag and drop widgets from the Components menu to the default variant, as required.
9. Highlight the unassigned variant by clicking its name. You now have several configuration
options available for the unassigned variant. These include, customizing the slot,
choosing a target audience, or, configuring the slot settings, as described below:
Note: Audiences are defined when a set of rules are created based on attributes of the
shopper profile, and are then used for personalizing the shopper’s experience. See
Define Audiences for more details.
To customize the slot, click the following options:

4-7
 Chapter 4
Customize slots

• Add variant ‘+’ button on the far right to add up to a maximum 10 variants,
these can be easily re-ordered via drag and drop.
Note: The order of the variants follows a left to right sequence, with the
leftmost variant (after the default) having the highest priority.
• Remove variant ‘x’ button to the right of each variant name to remove it. You
cannot remove the default, and you must have at least one variant in addition
to that default.
• Target icon to open the targeting modal, where you can name each variant as
required. (This modal can also be opened by double clicking the variant
name.)
To target an audience:
• Click the target icon to display the target audience configuration options.
• Enter the name of the variant.
• Select your target audience name. This can be chosen from a list of
predefined audiences as soon as you being typing. You cannot assign an
audience to the default variant.
• Choose your audience from the list of available audiences.
• (Optional) Select a start and end date.
Note: Results vary depending on the combination of dates and audiences
chosen: you can select a date without specifying an audience, in which case,
the default of ‘All Shoppers’ is applied; you can select an audience without
specifying start and end dates, in which case, the results are shown for an
immediate start date, and an indefinite end date; when a start date is not
specified, the results shown relate to an immediate start date; when an end
date is not specified, the results shown relate to an indefinite end date.
• Click ‘Add a Variant’ if you wish to add more variant slots.
Note: You can reorder the variants by dragging each one to a new position of
priority.
To configure the slot settings:
• Click the Settings icon to display the configuration options.
• Choose your slot name and description details.
• Click Save to confirm your settings.
10. Save your configurations.

11. Drag and drop widgets from the Components menu to the variant(s) as required.
Note: You can drag a Progress Tracker, Vertical tabs, or an Accordion stack on to
the variants of a slot, sometimes referred to as a nested stack.
12. You must ensure that you publish the changes made to your store after assigning
audiences to slots, otherwise the personalized content will not be displayed on the
storefront.
Configure role-based content slots
When an Agent accesses your store in order to gain insight into a shopper’s
perspective, they can view content based on their access role. You can, therefore
create several versions of your store where the content is determined by the relevant
access role. For example, the role of an Agent Supervisor, Administrator, or an
Account Manager may be assumed. See Create new orders for more details.

4-8
 Chapter 4
Customize slots

To configure a role-based content slot:

1. Open the Design icon and display the Layout tab.
2. Navigate to any layout by using the filter options.
3. Select your preferred layout and click the Grid View icon.
4. Locate the relevant section where you would like to add a role-based content slot and
highlight an existing region.
5. Either:
Select an existing region and ensure all widgets are removed so that just the region itself
remains.
Or
Add a new row (which contains regions) above or below using the arrows on the row
menu bar.
6. See Work with layout components for details on adjusting a region’s width settings, and
removing widgets
7. Open the Components menu, select the ‘Role Based Slot’ option, and drag to the empty
region. You will see a control (or default) variant, and an unassigned variant.
8. Highlight the unassigned variant by clicking its name. You now have several configuration
options available for the unassigned variant. These include, customizing the slot,
configuring the slot settings, or choosing an Agent access role, as described below:
To customize the slot, click the following options:
• Add variant ‘+’ button on the far right to add up to a maximum 10 variants, these can
be easily re-ordered via drag and drop.
• Remove variant ‘x’ button to the right of each variant name to remove it. You cannot
remove the default, and you must have at least one variant in addition to that default.
• Target icon to open the targeting modal, where you can name each variant as
required. (This modal can also be opened by double clicking the variant name.)
To configure your slot settings:
• Click the Settings icon to display the configuration options.
• Choose your slot name and description details.
• Click Save to confirm your settings.
Role-based slot variants provide access differently than other roles. Roles are generally
only containers and do not provide access by themselves. Roles contain privileges that
provide access. However, role-based slots variants do provide access. Ensure that you
are providing the correct level of access for your users by setting up the variants
correctly.
The following example shows how role-based slots work:
• You define a role-based content slot and configures one variant for the CS Agent
role, which is a container for the CS Agent privilege and another variant for the CS
Agent Supervisor role, which is a container for the CS Agent Supervisor role.
• You then create a custom role, Special Agent, that contains the CS Agent, Marketing
and Preview privileges.
• Then you remove the CS Agent role from a specific user and give that user the
Special Agent role instead.

4-9
 Chapter 4
Customize stacks

• The user no longer sees the content in the variant for CS Agent, even though
they have the CS Agent privilege. Because of the differences with role-based
slot variants, you must ensure that you add Special Agent to the CS Agent
variant.
To select the Agent access role:
• Click the target icon to display the access role configuration options.
• Enter the name of the variant.
• Choose your role from the list of available roles. This can be chosen from a list
of predefined roles as soon as you being typing. You cannot assign a role to
the default variant.
• Click ‘Add a Variant’ if you wish to add more variant slots.
Note: You can reorder the variants by dragging each one to a new position of
priority.
9. Save your configurations.
10. Drag and drop widgets from the Components menu to the variant(s) as required.
Note: You can drag a Progress Tracker, Vertical tabs, or an Accordion stack on to
the variants of a slot, sometimes referred to as a nested stack.
11. You must ensure that you publish the changes made to your store after assigning
audiences to slots, otherwise the personalized content will not be displayed on the
storefront.

Customize stacks
Stacks enable you to group related widgets in to a distinct set of steps which can then
be used for functional, navigational, or display purposes.

This section applies to Storefront Classic only.

The Progress Tracker, Vertical tabs, and Accordion stack options are available via the
Components tool. You can also create a Popup stack that allows you to provide a
summarized view of a product.
Add a Progress Tracker
You can use the Progress Tracker to add steps to your checkout flow. Adding progress
tracker steps guides shoppers through the checkout process in a series of easy to
follow stages, right up until they ultimately pay for their item(s).
Note: The Progress Tracker is only available within the Checkout layout.
To create the Progress Tracker:
1. Click the Design icon and display the Layout tab.
2. Navigate to the Checkout Layout using the filter options.
3. Select the Checkout Layout, and click the Grid View icon.
4. Locate the relevant section where you want to add a progress tracker and click to
highlight an existing region.
5. Either:

4-10
 Chapter 4
Customize stacks

Click an existing region and ensure all widgets are removed so that only the region itself
remains.
Or
Add a row (which contains regions) above or below using the arrows on the row menu
bar.
6. See Work with layout components for details.
7. Open the Components menu, select Progress Tracker, and drag to the empty region.
You will see a default Progress Tracker containing three steps. You can now customize
the steps as required, or, you can configure the settings.
To customize the steps, click the following options:
• Add Step ‘+’ button on the far right of the Progress Tracker to add up to 10 steps.
Each step must follow concurrently.
• Remove Step ‘x’ button to the right of each step name to remove a step. You must
have at least one step.
• Step name to open the Step Label box where you can rename each step as required.
To configure the settings:
• Click the Settings icon to display the configuration options.
• Choose your text alignment, background and step text colors, and button labels. You
can also select whether you want to allow the user to go back a step by checking the
Show “Previous” Button.
• Click Save to confirm your settings.
8. Drag and drop widgets from the Components menu to each of the steps as required.
Widgets can be dragged onto the currently active step; otherwise, you can drag a widget
to the name of a step (which is then automatically activated).
Note: You can drag a Progress Tracker, Vertical tabs, or an Accordion stack to the steps
of a stack, sometimes referred to as a nested stack.
Add vertical tabs
Adding vertical tabs to your web store enables shoppers to view a menu of associated
categories as a vertical display. They can be used to vertically stack associated information in
any layout and provide a means of avoiding too much screen content, and excessive
scrolling.
Note: Account-based users can use vertical tab stacks as a dedicated section for the
Shopper Profile, including, account details, address book, update password, and so on.
To add vertical tabs:
1. Click the Design icon and display the Layout tab.
2. Navigate to any layout by using the filter options.
3. Select your preferred layout and click the Grid View icon.
4. Locate the relevant section where you want to add vertical tabs and click to highlight an
existing region.
5. Either:
Click an existing region and ensure all widgets are removed so that only the region itself
remains.

4-11
 Chapter 4
Customize stacks

Or
Add a row (which contains regions) above or below using the arrows on the row
menu bar.
6. See Work with layout components for details.
7. Open the Components menu, select Vertical Tabs, and drag to the empty region.
You will see a default set of vertical tabs containing three steps. You can
customize these steps as required, or you can configure the settings.
To customize the tabs, click the following options:
• Add Step ‘+’ button on the far right of the vertical tabs to add up to 10 steps.
Each step must follow concurrently.
• Remove Step ‘x’ button to the right of each step name to remove a step. You
must have at least one step.
• Step name to open the Step Label box where you can rename each step as
required.
To configure the settings:
• Click the Settings icon to display the configuration options.
• Enter a name or notes, as required, and click Save to confirm your settings.
8. Drag and drop the required widgets from the Components menu to each of the
steps.
Widgets can be dragged on to the currently active step, otherwise, you can drag a
widget to the name of a step (which is then automatically activated).
Note: You can drag a Progress Tracker, Vertical tabs, or an Accordion stack to the
steps of a stack, sometimes referred to as a nested stack.
Add accordion stacks
Adding accordion stacks to your web store enables shoppers to view a menu of
associated categories as a progression of steps. They can be used to stack
associated information in any layout and provide a means of avoiding too much screen
content, and excessive scrolling.
To add accordion stacks:
1. Click the Design icon and display the Layout tab.
2. Navigate to any layout by using the filter options.
3. Select your preferred layout and click the Grid View icon.
4. Locate the relevant section where you want to add accordion stacks and click to
highlight an existing region.
5. Either:
Click an existing region and ensure all widgets are removed so that only the region
itself remains.
Or
Add a new row (which contains regions) above or below using the arrows on the
row menu bar.
6. See Work with layout components for details.
7. Open the Components menu, select Accordion and drag to the empty region.

4-12
 Chapter 4
Customize stacks

You will see a default set of accordion stacks containing three steps. You can now
customize the steps as required, or you can configure the settings.
To customize the accordion stacks, click the following options:
• Add Step ‘+’ button on the far right of the vertical tabs to add up to 10 steps. Each
step must follow concurrently.
• Remove Step ‘x’ button to the right of each step name to remove a step. You must
have at least one step.
To configure the Accordion settings:
• Click the Settings icon to display the configuration options.
• Enter a name or notes within the About tab.
• Select the text alignment and colors for each of the steps within the Settings tab.
• Click Save to confirm your settings, otherwise cancel.
8. Drag and drop the required widgets from the Components menu to each of the steps.
Widgets can be dragged on to the currently active step, otherwise, you can drag a widget
to the name of a step (which is then automatically activated).
Note: You can drag a Progress Tracker, Vertical tabs, or an Accordion stack to the steps
of a stack, sometimes referred to as a nested stack.
Add popup stacks
Adding popup stacks to your web store enables you to manage and configure content to be
displayed as a screen that opens, or pops-up, in front of the one you are currently viewing.
Popup stacks contain a Main sub-region, and a Popup sub-region. These can be used by
shoppers, for example, when they click a button and a log in/registration details page opens
as a popup screen, or, when they are viewing a list of products and they click to open one in
a summarized quick view popup screen.
To add popup stacks:
1. Click the Design icon and display the Layout tab.
2. Navigate to any layout by using the filter options.
3. Select your preferred layout and click the Grid View icon.
4. Locate the relevant section where you want to add a popup stack and click to highlight an
existing region.
5. Either:
Click an existing region and ensure all widgets are removed so that only the region itself
remains.
Or
Add a new row (which contains regions) above or below using the arrows on the row
menu bar.
6. See Work with layout components for details.
7. Open the Components menu, select Popup Stack and drag to the empty region.
You will see two default sub-regions; Main, and Popup.
8. Open the Main sub-region. You can add a widget to the Main sub-region which triggers
the display of the widget in the Popup sub-region. In order for this to happen, you must
do the following:

4-13
 Chapter 4
Modify your page layout settings

• Drag and drop the required widget from the Components menu to the Main
sub-region.
• Open the widget’s Settings icon to display the configuration options, and open
the About tab.
• Click the Go to Widget Code button.
The Template window opens, displaying lines of HTML code.
From here, you can also edit the widget’s style sheet, text snippets, or download
the source file. See Modify a component’s code for more details.
• Locate where in the template you wish to place the link that will launch the
popup. An example of the link you may add to the code is shown below:

<a href="#" data-toggle="modal" data-bind="attr: {'data-

target':$popupId}">Launch Popup</a>

9. Click Save to confirm your settings; otherwise click Cancel.

10. Open the Popup sub-region and complete the following steps:

• Drag and drop the required widget from the Components menu to the Popup
sub-region.
• Open the widget’s Settings icon to display the configuration options, and edit
as required.
Add a Quick View Popup Stack
An instance of the Popup Stack, known as the Quick View Popup Stack, is located
within the Collection and Search Results layouts and enables shoppers to see a
summarized view of a product. From there, they can then expand to view the full
product details, if required.
You can create other instances of the Quick View Popup Stack. See Understand
widgets for more details.
The Quick View Popup Stack is automatically provided with the following widget
instances:
• Product Listing widget within the Main sub-region of the Collections layout.
• Search Results widget within the Main sub-region of the Search Results layout.
• Product Quick View widget within the Popup sub-region for both the Collection and
Search Results layouts. This widget instance is an instance of the Product Details
widget for the selected product.

Modify your page layout settings

You can customize your store’s page layouts by modifying the layout settings for each
of them.

This section applies to Storefront Classic only.

Some common configuration settings across all layouts allow you to name the layout
and add reminder notes. Many of the layouts also allow you to create a page title, add
metadata to be used by search engines, and provide you with general information
relating to default layouts.

4-14
 Chapter 4
Modify your page layout settings

In addition to those settings already mentioned, you can apply viewport(s) to newly created
layouts. Refer to Create a new layout instance (cloning) for further information on new
layouts. As default layouts apply to all viewports, if you check the Make Default Layout box in
your new layout, then viewport options are no longer available.
To access the configuration settings for layouts:
1. Open the Design page and click the Layout tab.
2. Select your preferred layout and click either the Layout Settings icon, or the layout
name. The settings window for the chosen layout opens.
3. Customize the layout settings, as required. You can refer to the settings table below for
details.
You can also delete any of the layouts by clicking the Delete button located on the bottom left
of any of the layout settings. However, given that default layouts cannot be deleted, you may
notice that the delete button is not an option for default layouts.
The following table describes the layout settings and shows the layouts to which each setting
belongs.

Setting Layout Description

Layout Name All layouts Enter a unique name for the
layout.
Notes All layouts Record general notes for internal
use.
Page Title Home Enter an alphanumeric page title,
Checkout giving consideration to
maximizing the best search
Order Confirmation
engine results.
All Article layouts
Error
Payer Authentication
Wish List
Order Details
Order History
Scheduled Order
Assets
Asset Details
Page Address Checkout The page address is appended
All Article layouts to the URL for your store to
create a link to the page. The
page address: cannot contain
spaces or special characters,
can be used for multiple Article
layout page types with various
viewport assignments, must be
unique for layouts other than the
Article layout types, cannot be
used simultaneously on a non-
Article and an Article layout page
type (applies across all Article
Layout instances).

4-15
 Chapter 4
Modify your page layout settings

Setting Layout Description

Add New Meta Tag Home Add details of meta tag
Collection attributes, value and content.
Product
Cart
Checkout
Order Confirmation
All Article layouts
Error
Search Results
No Search Results
Payer Authentication
Wish List
Layout Preview – Product ID Product Add the relevant Product ID.
Layout Preview – Collection Collection Select a Collection from the
available list, for example,
Apparel/Women/Dresses.
Cart Preview Cart Add up to 5 Product ID(s) along
Order Confirmation with their quantity.

Order Status Checkout Select from the list of order

statuses.
Viewports Cart Select a viewport to suit the
Checkout visible area of the display page.
All Article layouts
Sites Cart Assign layout pages to one or
Checkout more sites, when running
multiple sites from your Oracle
All Article layouts
Commerce instance.
Make Default Layout Cart Check to make this the default
Checkout layout.

Display layout to account Cart Check to confirm this layout is for

shoppers only All Article layouts display to account shoppers only.

SEO Metadata – Meta Home Enter a description for SEO

Description All Article layouts metadata that will be useful for
search engine results.
SEO Metadata – Meta Keywords Home Enter page content keywords for
All Article layouts SEO metadata that will be useful
for search engine results.

Assign layouts to sites

When running multiple sites from your Oracle Commerce instance, you can assign
layouts to one or more sites. Each site corresponds to an individual store and can
have its own catalog. See Run Multiple Stores from One Commerce Instance for more
details.
To assign a layout to a site:
1. Click the Design icon and display the Layout tab.

4-16
 Chapter 4
Upgrade deployed widgets

2. Select the page layout for which you wish to assign sites, and click the Layout Settings
icon. (The preceding table highlights which page layouts can be assigned to sites.)
Note: When you have multiple instances of layouts, using the search box to filter for your
preferred layout may avoid excessive scrolling.
3. Scroll to the Sites option and begin typing the name of your preferred site. A filtered list of
matching sites is displayed.
4. Select the site(s) you wish to assign.
5. Click Save to confirm your selections.

Upgrade deployed widgets

Widget instances that have been deployed are not automatically upgraded when new
versions of the widgets are released. This protects deployed widgets that have been
customized from failing if the customizations are not compatible with the upgrades.

This section applies to Storefront Classic only.

In order to use a new version of a widget, you must remove any existing instances of the
widget from your page layouts and replace them with the upgraded version. You also need to
re-create any template or style sheet customizations for the upgraded widget.
To upgrade a deployed widget:
1. Make a copy of the template and style sheet code before the existing widget instances
are deleted, and save the copy to an external file.
Note: This code can be used as a reference for editing the new widgets once they are
placed in the page layouts.
2. Log in to the Oracle Commerce administration interface.
3. Click the Design icon.
4. From the Layout tab, select the page layout that contains the widget you want to
upgrade.
Note: When you have multiple instances of layouts, using the search box to filter for your
preferred layout may avoid excessive scrolling.
5. Click the Grid View icon.
6. Locate the widget on the page. Click the X icon to delete the instance.
7. At the bottom of the page, click Components.
8. Drag the upgraded widget and drop it in the same location as the widget you deleted.
9. Repeat these steps for all instances of the widget.
10. Edit the widget to include any modifications made to the previous instance. From the
Component tab on the Design page, double click and open the instance in Grid View,
click the About tab and click the Go To Widget Code button. Base these changes on the
copy you made before deleting the widgets.

4-17
 Chapter 4
Work with role-based layouts

Work with role-based layouts

When reviewing your storefront in Preview, you can use role-based layouts that render
exclusively for selected roles.

This section applies to Storefront Classic only.

The layout only renders in Preview if the user is authenticated and matches one of the
designated roles.
Layouts of this type can be used in conjunction with any Commerce roles. For
example, you can use this feature to preview a page exclusively for developers with
the Design role, allowing them to test changes before they are made on the production
storefront application.
Role-based layouts provide access differently than other roles. Roles are generally
only containers and do not provide access by themselves. Roles contain privileges
that provide access. However, role-based layouts do provide access. Ensure that you
are providing the correct level of access for your users by setting up the layouts
correctly.
The following example shows how role-based layouts work:
• You define a role-based layout to be viewed in Preview by developers with the
Design role. The Design role is a container for the Design privilege.
• You then create a custom role, Special Designer, that contains the Design,
Marketing and Preview privileges.
• Then you remove the Design role from a specific user and give that user the
Special Designer role instead.
• The user no longer sees the layout in Preview, even though they have the Design
privilege. Because of the differences with role-based layouts, you must ensure that
you add Special Designer to the layout.
To create a role-based layout:
1. Access the role-based layout from the Design page, Layout tab.
2. Navigate to the Role layout by using the filter options.
3. On the Layout Settings, Role Layout dialog, create a layout name, set the layout
as the default layout (optional), and, if you are working with a cloned layout, select
the applicable viewport(s).
4. Click the Role field to use the role picker functionality. You can select one or more
roles for this layout.
Note: If a role is not selected in the Role field, or if the selected role is deleted, the
layout is not rendered in Preview, even if accessed by an administrator, agent, or
agent supervisor role.
5. Name the role display name.
6. For a cloned layout, include the page address and display name if applicable.
7. Click Save.
Once you have completed configuring the settings, create the page for Preview as you
would with any other layout, using grid view, components, and elements.

4-18
 Chapter 4
Preview your store

Preview your store

You can preview your web store as you make changes to it, without the need to publish live.
To preview, open your chosen layout via the Grid View icon. Click the Layout Preview option
from the layout configuration menu and you are automatically shown the relevant layout in
the preview pane.
Additionally, you can click Preview from the layout configuration menu to display the full
screen web store preview. Note: In environments running multiple sites from one Oracle
Commerce instance, the particular layout associated with the site is displayed, and you can
choose which site to view.
See Preview your changes for information about customizing a preview session.
Changes made to your storefront do not appear on your live store until you publish them. See
Publish Changes for more details.

4-19
5
Customize Your Store’s Design Theme
A theme is a set of styling configurations, including colors, fonts, and other design elements,
that defines the overall look and feel of your online store.
Commerce provides a default theme that you can copy and customize as required.
To access themes, click the Design page and open the Theme tab.

Understand the default theme

Opening the Theme tab displays the sample theme. This is automatically activated as the
default theme, highlighted by the Active icon.

This section applies to Storefront Classic only.

The default theme contains pre-configured settings that can help you start creating your own
web store. You can make adjustments to the settings, as required, once you have cloned the
theme. You will be able to see those configuration changes in your store/preview after you
have activated the newly customized theme.
Details on cloning and configuring your style settings are described in the following sections.

Create a new theme (cloning)

Creating a new version, or cloning a copy of an existing theme, is possible for any theme
including the one that is currently active.

This section applies to Storefront Classic only.

To create a new theme:

1. Open the Design page and click Theme.
Note: When you are designing your web store for the first time, the currently active theme
is displayed with the Active icon highlighted and a message instructing you to clone the
theme before customizing settings.
2. Click the Clone Theme button.
3. Enter a unique name for the cloned theme.
4. Click Save to confirm.
Alternatively, you can also choose to make another copy of your newly cloned theme by
clicking Clone Theme. All configurations related to the activated theme are now available
to view or customize.

5-1
 Chapter 5
Customize your theme

Customize your theme

You can customize your theme’s background, buttons and navigation tools. You can
also customize the typography settings.

This section applies to Storefront Classic only.

This section includes the following information:

• Access basic theme information
• Style your theme’s background
• Style your theme’s buttons and navigation tools
• Customize your theme’s typography setting
• Compile your customized theme

Access basic theme information

The About menu tab displays basic information related to any given theme. Such
information includes Theme Name, Sites, Theme Notes, and details about the theme
from which the current theme has been cloned.
You can edit the Theme Name and Theme Notes as required. You can also make a
clone of your theme by clicking the Clone Theme button, regardless of whether or not
the theme you are cloning is active.
Clicking the Go to Theme Code button opens that theme’s code for editing.

Style your theme’s background

The Backgrounds menu tab displays details on style, header, footer and navigation
settings relevant to any given theme.
Background style settings
These settings allow you to choose an image or background color to be used as the
backdrop for your web store.
Use these style settings to adjust the positioning, color settings, and repeat patterns
for your web store’s background.
Header row
These settings allow you to choose an image or background color to be used as the
backdrop for your web store’s top row header. This refers to the upper part of the
header bar running across the top of your web pages. This section contains site links
and customer login links.
Use these style settings to adjust the positioning, color settings, and repeat patterns
for your Header Top Row.
Footer row
These settings allow you to choose an image or background colors to be used as the
backdrop for your web store’s footer. This refers to the bottom section of your web
pages.

5-2
 Chapter 5
Customize your theme

Use these style settings to adjust the positioning, color settings, and repeat patterns for your
Footer.

Style your theme’s buttons and navigation tools

Your theme’s Buttons & Nav Menu tab displays details on style settings, colors, fonts, and
sizes when using buttons and navigation colors within your web store.
Buttons
Choose your theme’s button style settings for use throughout your web store. Button style
settings include sizes, styles, colors, and fonts for both primary and secondary button types.
Navigation color settings
Choose your theme’s color settings for use throughout your web store’s navigation.
Navigation color settings include top level, drop-down, and mobile navigation color settings.

Customize your theme’s typography setting

Choose your theme’s typography settings for use throughout your web store. Typography
settings enable you to set up various link colors as well as your default base font settings,
and you can add new fonts via an external URL. The Link Color and Base Font Settings
can be inherited throughout all heading styles, or you can edit the heading styles and make
any changes you require to each one individually.

Compile your customized theme

Themes are compiled automatically. However, you can also compile a theme manually after
customization changes have been made, for example when you have added a new widget to
a layout, or you have changed a theme’s code by updating a widget/stack Less file. You can
also compile a theme manually if a compile build has failed.
To do so:
1. On the Design page, click the Theme tab.
2. Click the Theme Compilation tab.
3. Click Build Theme.
4. Click Save to save the compiled changes.
If you have a significant number of sites, you may find that you must wait a considerable
amount of time for all pending automatic theme compilations that occur when you publish
your changes. You can use the following endpoints to disable automatic theme compilation,
where themes are compiled automatically when changes occur. For example when updates
to stacks, slots, or page layouts are updated.
You can use the Admin API to review and set automatic compilation of themes.
To obtain the compilation settings for themes, issue a GET command to /ccadmin/v1/
themes/compilationSettings/getThemeCompilationSettings. A successful
response body will contain the compileThemesAutomatically boolean property that indicates
if themes will be compiled automatically.
To configure compilation settings for themes, issue a PUT command to /ccadmin/v1/
themes/compilationSettings/setThemeCompilationSettings with the
compileThemesAutomatically property set to true or false. Setting the property to true
indicates that the theme should be automatically compiled. If automatic theme compilation is

5-3
 Chapter 5
Modify theme code

disabled, you will need to manually compile your themes using the Themes tab of and
administration interface before publishing any assets that contain style updates.
Once you have issued a PUT command, a successful response body contains the
compileThemesAutomatically property that indicates whether or not the theme will be
compiled automatically. Note that if compilation settings are invalid or cannot be saved,
the 70030 error, which indicates that one or more of the given compilation settings is
invalid, or the 70031 error, which indicates that an error occurred when trying to save
the compilation settings, will display.

Modify theme code

You use the code editing options available within the Theme tab to modify the theme's
CSS.

This section applies to Storefront Classic only.

To modify theme code:

1. Open the Theme option on the Design page.
2. Scroll to the Theme CSS section, where all your web store’s themes reside.
3. Select the theme you want to edit.
The design code window for that Theme CSS opens.
4. Choose to make your edits using any of the following options:
• The Style Variables option accesses the variables file.
• The Style Sheet option accesses the full theme Less/CSS.
Note: Editing the theme code locks the theme UI editor. You can unlock the UI
editor by clicking the Restore button to revert to the last version of the theme
saved via the theme UI editor, however, you will lose any changes made to the
design code.
• The Additional CSS option appends to the end of the style sheet.
You can append additional CSS for each individual Theme CSS. The
additional code entered is appended to the end of the global style sheet. If you
add CSS to this tab and do not modify the code on the Style Variables or
Style Sheet tabs, then you are not locked from editing that theme in the theme
UI editor.
A separate custom CSS file exists for each theme.
5. Modify the code as required.
6. Save your changes.
Customize theme bootstrap variables
Your storefront Theme CSS is made up of Bootstrap Less files and widget-specific
Less files. You can use the Style Variables option within the Theme CSS to customize,
and add to, a theme’s bootstrap style variables. For example, if you would like to
change your theme’s viewport sizes, you can copy the Bootstrap variable from your
Bootstrap documentation and paste it to the end of the Style Variables file, for
instance:
@screen-sm-min: 720px.

5-4
 Chapter 5
Apply a theme to a site

See Configure a widget’s style for more information.

Apply a theme to a site

When your Oracle Commerce instance runs multiple sites, you can apply a theme to any
given site.

This section applies to Storefront Classic only.

To apply a theme to a site:

1. Open the Settings page, which automatically lands on the Setup settings.
2. Click the General tab.
3. Either:
• Enter settings details to create a new site. See Enter basic store information for
further information.
• Choose your site from the site picker search box above the Settings menu options to
open a site already created.
4. Scroll to the Theme drop down list and choose the theme you wish to activate for the
site.
5. Save your changes to confirm.
Upon opening the Theme tab on the Design page, you will see the Active icon next to the
theme that has been activated for that particular site within the Custom Themes section.

Delete a theme
To delete a theme, click Theme on the Design page, and then open the theme you wish to
delete.

This section applies to Storefront Classic only.

You can delete any opened theme by clicking the Delete button at the bottom of any of the
configuration settings tabs. A message displays confirming the successful deletion of the
theme.
Note: You cannot delete the currently active theme or any purchased themes.

5-5
6
Modify Your Storefront Using Code Editing
Tools
Several code editing options, primarily aimed at developers, are available within the Design
page. They enable you to work with widget code, theme variables, CSS style sheets, style
variables, text snippets, and component libraries.
Important: Caution should be taken at all times when editing and publishing code as any
changes can have an adverse effect on your site’s functionality. See Publish Changes for
more details.

Modify a component’s code

You can modify a component’s code via the HTML template, style sheets, or text snippets.

This section applies to Storefront Classic only.

To modify a component's code:
1. Open the Design page and click Components.
2. Filter the components that are displayed by choosing from the Type or Source filters. You
can also search for a specific component by entering details in to a Filter box.
3. A list of components displays which includes overview information on the component
type, the number of associated instances, and the latest version number. There are also
several customization options available.
4. Select the component you wish to edit and click either its name or the Details icon. The
component details open to display overview information on the list of instances, the
component type, the number of associated instances, the latest version number, and the
layout(s) associated with the component.
5. (Optional) The Extend JavaScript button is visible for non-extension widgets. Click the
button to open the JavaScript file and modify the code. For more information on this
feature, see Use the JavaScript Code Layering User Interface feature.
Note: The widget JavaScript is only editable for custom widgets that have had their
editable JavaScript property activated.

6. Click the icon to go to the coding options page. The HTML Template window
automatically opens, displaying lines of HTML code. Immediately above the menu tabs is
the Settings icon, which you can select if you wish to make changes to the component
settings.
7. Depending on the task you wish to perform, you can now either:
• Modify the code within the HTML Template option.
• Modify the Less/CSS by selecting the Style Sheet option. Oracle Commerce makes
use of Less in the style sheets. Less is a CSS pre-processor which requires the style
sheet files to be compiled to produce CSS and provides additional features such as
variables and functions. For further details on Less, refer to [Link]

6-1
 Chapter 6
Modify the theme CSS style sheet

• Modify the component’s text by selecting the Text Snippets option. See
Customize your web store’s text for more information on modifying your store’s
global text.
All available values for your chosen component are displayed as editable links.
– Click to open the value you wish to edit.
– Enter the new value and confirm or reject the edits using either the Save
or Close icons.
8. (Optional) Click the Download Source button to download the widget file for each
widget instance.
9. Click Save.

Modify the theme CSS style sheet

You can manipulate the CSS for each individual theme CSS.

This section applies to Storefront Classic only.

The code is available for editing from within the Theme option. See Modify theme code
for more information.

Use developer tools to customize your store

The Developer option in the Design page gives you access to extended coding
features that allow you to change the text displayed to customers on your store and
export and import design elements from one Oracle Commerce instance to another.

This section applies to Storefront Classic only.

Customize your web store’s text

Text snippets enable you to directly access your web store’s customizable global text,
which can include messages, labels and help tips. You can also customize the text
contained within individual components. See Modify a component’s code for more
details.
To customize your web store’s text:
1. Open the Design page and click Developer.
2. Select Text Snippet.
3. Choose the Text Snippet Type from the drop down list, or begin typing the name
in the filter box. All available values for your chosen type are displayed as editable
links.
4. Click the value you wish to edit.
5. Enter the new value and confirm or reject the edits using either the Save or Close
icons.
Note: Text set between double underscore characters, such as __totalPrice__,
represents a parameter that will be replaced with the appropriate value when the
resource is displayed in your web store. Such parameters can be moved within a
resource value or deleted from it. However, you should avoid changing the name
of the parameter, or the replacement will not work.

6-2
 Chapter 6
Use developer tools to customize your store

Text in brackets preceded by $t indicates an additional resource look-up is occurring. For

example, $t([Link]:[Link]) indicates that the value for the ‘option’
resource will be inserted at this position in the current resource value.

Customize your store’s code using the Design Code Utility tool
The Design Code Utility is a command-line tool that integrates Oracle Commerce with your
IDE or code editor. It allows you to customize user-modifiable source code from a Commerce
server and then upload it again.
To access the Design Code Utility:
1. Open the Design page and click Developer.
2. Select Developer Tools.
3. Under Design Code Utility, click Download.
4. Save the ZIP file to a location on your local machine and extract its contents.
See Use the Design Code Utility for more details.

Use server-side extensions

Some Oracle Commerce features are implemented as server-side extensions that can run on
the [Link] server associated with your Commerce environment. To use one of these
features, you must download the extension from the Commerce administration server. You
can then optionally customize the extension and upload it to your [Link] server.

To download a server-side extension:

1. Open the Design page and click Developer.
2. Select Server-Side Extensions. A list of files available for download is displayed.
3. Find the ZIP file for the server-side extension you want to download.
4. Click the associated Download Extension icon and save the file to a location on your
local machine.
The list of files available for download includes application files and library files. For example,
for the punchout feature, there is an application file named [Link] and a
library file named [Link]. The application file contains the complete extension
(including the library module), so you typically need to download only it and not the library file.
The library file contains the business logic for the extension, and it is provided as a separate
download so you can obtain updates when they are supplied.
To customize a server-side extension you have downloaded, you must first extract the
contents of the ZIP file. Note that when you customize the extension, you should not make
any changes to the library module, which is found in the following directory in the extension:

node_modules/@oracle-commerce-cloud/<SSE_name>-lib

For example, the punchout library module is found here:

node_modules/@oracle-commerce-cloud/punchout-lib

When you have finished your modifications, reassemble the application ZIP file and use the
POST /ccadmin/v1/serverExtensions endpoint to upload it to your [Link] server.

6-3
 Chapter 6
Use developer tools to customize your store

Update the library in a server-side extension

After you have downloaded the application file for a server-side extension and
extracted the contents to a directory, you can replace the library module with an
updated version (if one is available).
To update the library in a server-side extension:
1. Download the library file for the extension. For example, for the punchout
extension, download [Link].
2. Extract the contents of the library file.
3. Use the extracted contents of the library file to replace the library module in the
extension application.
4. Reassemble the application ZIP file and use the POST /ccadmin/v1/
serverExtensions endpoint to upload it to your [Link] server.
For more information about developing server-side extensions, see the following post
on the Oracle Partner Network:
[Link]
working-with-commerce-cloud-server-side-extensions

Change the storefront framework version

The storefront framework comprises the JavaScript and CSS files used to manage
many of the widget and theme elements that can appear in your storefront, including
code that has been customized by your developers. You can choose to restore the
previous version of the storefront framework or upgrade to the latest version. See
Restore or upgrade the storefront framework version for more details.

6-4
7
Manage Your Catalog
A catalog organizes your products, SKUs, and collections in a hierarchy that reflects the way
users will navigate to them on your store. Your store contains only one catalog, but that
catalog can contain any number of collections, which can contain any number of products
and associated SKUs.
Note: Your store may be configured to allow the assignment of catalogs to business
accounts. See Configure Business Accounts for information about accounts and contacts.
If a user does not have the correct access to a catalog the following conditions apply:
• The editors for the catalog and its collections, products and SKUs will be read-only. If a
collection of product also belongs to other catalogs to which the user does have access,
the item will be editable.
• UI controls for actions that the user cannot perform may be hidden or disabled.
• Some icons and menu options will change from Edit to View.
• In some catalog pickers, some items will be unavailable.
The topics in this section describe how to set up and manage your catalog.

Understand catalogs
A catalog organizes your products, SKUs, and collections in a hierarchy that reflects the way
users will navigate to them on your store.
A catalog contains collections, which in turn, contain products.
By default, Commerce includes a single catalog called Product Catalog, where you can
create all the collections, products, and SKUs available to your store. There are times,
though, when you might want to provide shoppers with a more customized shopping
experience by creating additional catalogs. You can create and assign additional catalogs in
the following instances:
• Multiple stores: You can run multiple stores (called sites) from a single instance of
Commerce. Each site has a unique domain and you can assign each site its own catalog.
For example, suppose you sell soccer jerseys. You could create a separate store for each
team whose jerseys you sell. You would assign each store a catalog that contains only
products for that team. Fans could easily find and purchase their team’s gear without
having to sift through merchandise for other teams. For details about running multiple
sites, see Run Multiple Stores from One Commerce Instance.
• Account-based stores: Commerce lets you create accounts for companies that do
business with you, such as manufacturers, distributors, and wholesalers. You can provide
each account with a catalog that meets its specific business requirements. It is unlikely
that all account-based shoppers will need to purchase all products your store sells, so
providing an account with its own focused catalog makes it easier for those shoppers to
find and purchase the right products. Logged-in contacts who shop on your store can see
and purchase only the products in the catalog associated with their account. For details
about creating and managing accounts, see Configure Business Accounts.

7-1
 Chapter 7
Work with independent catalogs

• Rules set by an external system. By default, Commerce assigns catalogs and

price groups to sites or, for account-based commerce, to accounts. However, you
might want to override these default assignments with different catalogs and price
groups for each registered shopper. For example, you can personalize the catalog
and prices a shopper sees based on geographic location or level in a loyalty
program. For more information, see Assign Catalogs and Price Groups to
Shoppers.
Commerce lets you create the following types of catalogs:
• Independent catalogs are catalogs that are not dependent on any other catalog in
your environment. Collections you add to an independent catalog can be exclusive
to that catalog, or can be linked to a number of different catalogs. The Product
Catalog that Commerce includes by default is structured as an independent
catalog. See Work with independent catalogs for more information.
• Filtered catalogs provide custom views into the Product Catalog. Filtered catalogs
let you add products to a catalog without defining collections in that catalog
hierarchy. See Work with filtered catalogs for more information.
• Legacy catalogs are an older type of secondary catalogs that provide custom
views into the Product Catalog. See Work with legacy catalogs for more
information.

Work with independent catalogs

Independent catalogs are catalogs that are not dependent on any other catalog,
including the Product Catalog that is included with Commerce.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

An independent catalog can contain links to collections and products that are already
in other catalogs, or it can contain collections and products that are not associated
with any other catalogs.
All catalogs you create in the Commerce user interface are independent catalogs. (You
must use the Admin API to create legacy catalogs and filtered catalogs. See Work with
filtered catalogs and Work with legacy catalogs for more information.)

Understand independent catalog structure

You can perform all catalog-related tasks on any independent catalog:
• View details for a product or a collection.
• Create a new product or collection.
• Link an existing product or collection.
• Edit or delete an existing product or collection.
• Rearrange products in a collection or rearrange collection hierarchy.
• Access the following options from the Manage Catalogs menu: Product Types,
Price Groups, Inventory, and Upload Media.
Any changes you make to linked collections and products are automatically applied to
all independent catalogs that are linked to the items that were changed. See Link and
unlink collections and products for more information. Remember that you must publish
any changes you make to catalogs before they will appear on your stores.

7-2
 Chapter 7
Work with independent catalogs

Create independent catalogs

This section describes the steps you must complete to create a new independent catalog and
add or link collections to it.
To create a new independent catalog:
1. On the Catalog page, click Manage Catalogs and select New Catalog.
2. Enter values for the Catalog Name and Catalog ID.
You cannot change the Catalog ID once you create the catalog.
3. Click Create.
To add or link collections to a catalog:
1. Click the Collections link on the left-hand side of the catalog’s details page.
2. Click Edit.
3. Select a collection from the list. You can filter the list by typing or pasting some text in the
Collections box.
The filter control matches letters or numbers that you type, wherever they appear in the
name or ID, not just at the beginning. Usually, as you type more characters, there are
fewer matches. When you see the item you want, select it.
Note: Selecting a child collection does not add its parent collections to the catalog.
4. Click Add Selected.
5. Click Done when you finish adding collections.
6. (Optional) You can specify a default collection where Commerce creates products that
have no parents, for example, products that come in on a feed. Click the Select
Collection button and select a collection from this catalog.
If you do not select a default collection, Commerce creates products with no parents in
Unassigned Collections.
7. Click Save when you finish making changes.
8. Publish your changes. See Publish Changes for more information.

Edit and delete independent catalogs

You can change a catalog’s name and associated collections; you cannot change its ID. You
can delete a catalog that is not associated with any sites or accounts. You can delete any
additional catalogs that you created, but you cannot delete the Product Catalog that is
included with Commerce.
Important: Deleting assets, such as products, catalogs, shipping methods, etc., can result in
discrepancies in your system, which may produce errors. It is recommended that you disable
assets instead of delete them.
To edit or delete a catalog:
1. Select the catalog to edit or delete in one of the following ways:
• On the Catalog page, select a catalog from the drop-down list at the top of the
catalog page to display the catalog.
• On the Catalog page, click the Manage Catalogs button and select All Catalogs.
Click the name of the catalog you want to edit.

7-3
 Chapter 7
Work with filtered catalogs

2. To edit the catalog, click Edit Catalog, then change the catalog name or its
collections. Click Save when you finish making changes.
3. To delete the catalog, click Edit Catalog, then click the Delete button.
If the catalog is already associated with accounts or sites, you must first remove it
from all accounts or sites before you can delete it. See Work with account
contracts for information about removing a catalog from an account. See
Configure Sites for information about associating catalogs with sites.
You cannot delete a catalog that is the base catalog for a filtered catalog.

Work with filtered catalogs

A filtered catalog provides a filtered view of an existing independent catalog.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Filtered catalogs let merchants scale to a larger number of catalogs with less work and
provide flexibility for merchants who sell to a number of accounts or in a number of
countries. Filtered catalogs provide central management of collections and taxonomies
and give merchants fine-grained control of account-level availability of products.
While independent catalogs can contain different collections and products, a filtered
catalog references only products and collections that are already in its base
independent catalog; you can, however, show or hide selected products from within
the filtered view.
You must create the first new filtered catalog in your Commerce instance with the
Admin API or via import. Once you have created the initial catalog, you can work with
filtered catalogs on the Catalog page in the administration interface.
You can assign filtered catalogs to sites or, if your store supports account-based
commerce, to business accounts. You assign filtered catalogs in the same way you
assign independent catalogs. See Associate catalogs with sites or accounts for details.

Understand the benefits of filtered catalogs

Because filtered catalogs let merchants scale to a larger number of catalogs and
reduce manual duplication of effort, they are useful for merchants who share catalog
taxonomies (collection hierarchies) across catalogs but want to have unique product
membership per account or site.
This section describes two cases where a merchant would benefit from using filtered
catalogs.
• An account-based merchant has one large main catalog that contains all the
products the merchant sells.
The merchant sells to a large number of accounts and assigns the full main
catalog to about two-thirds of them. Each of the remaining accounts requires a
catalog that contains a subset of the products from the main catalog.
The merchant can set up a filtered view of the main catalog for each remaining
account. Each filtered view has the same taxonomy as the main catalog, but
contains only the products that are appropriate for the account to which it is
assigned. For example, 70% of the products from the main catalog can be marked
as core products that are available in all the filtered views. The remaining products
can be tagged as needed on a per-view basis.

7-4
 Chapter 7
Work with filtered catalogs

• A merchant has two main catalogs, one for sales in Europe and one for sales in North
America. They have country store sites for Spain, Germany, UK, France, Italy, the US,
Canada, and Mexico.
To avoid the need to recreate the hierarchy for each country catalog, the merchant
creates a filter view catalog based on the European catalog for each of the following
country stores: Spain, Germany, UK, France, and Italy.
Similarly, the merchant creates filtered catalogs based on the North American catalog for
Canada and Mexico. (The US store uses the full North Amercann catalog.)
The entire Wellness collection is not available in Spain, so a business user can hide all
products from this collection in the filtered view for the Spanish site. After she publishes
her changes, the Wellness collection no longer appears in the menu for the Spanish site.
Three products in the Nail Polish collection are not available for sale in Germany due to
ingredients restrictions. The business user can navigate to the Nail Polish Collection in
the German filtered view and hide the three products that are not available in Germany.
Once she publishes her changes she will see that three nail polishes are no longer
showing up in the Nail Polish Collection on the German site.
Similarly, the entire Footspa collection is not available in Canada, so a business user can
hide all products from this collection in the Canadian filtered view of the North American
catalog.
Keep in mind that performance can be impacted if each filtered view contains a large number
of non-core products. The best approach to filtered views is to have a set of core products
and filter out by exception.

Understand the structure of filtered catalogs

There are a number of tasks that you cannot perform in filtered catalogs. You can perform the
following tasks only in the independent catalog that the filtered view is based on:
• Create a new product or collection.
• Edit or delete an existing product or collection.
• Rearrange products in a collection or rearrange collection hierarchy.
• Work with product types, price groups, inventory, and media.
Any changes you make in a base independent catalog are automatically applied to the
filtered views that include the items that were changed. Remember that you must publish
your changes before they will appear on your stores.

Create a filtered catalog

The administration interface supports creating independent catalogs only. To create filtered
catalogs, you must use the Admin API.
Note: You can also create new filtered catalogs by using the CSV import feature. See Import
catalog items and inventory to learn how to create filtered catalogs by importing.
To create a catalog, you can use the createCatalog endpoint in the Admin API. The
catalogVersion and baseCatalog properties specify that you are creating a filtered catalog:

• Set the value of catalogVersion to 3 to specify that the createCatalog endpoint should
create a filtered catalog.
• The value of baseCatalog must be the catalog ID of an existing independent (version 2)
catalog. Otherwise, the request returns an error.

7-5
 Chapter 7
Work with filtered catalogs

The createCatalog request cannot associate collections with the new filtered catalog.
If the request includes categoryIds, an error is returned.

The following example uses the createCatalog endpoint to create a filtered catalog:

POST /ccadmin/v1/catalogs HTTP/1.1

Content-Type: application/json
x-ccasset-language: en

{
"catalogVersion": 3,
"catalogId": "catSpain",
"displayName": "Spain",
"baseCatalog": "catEuro"
}

The response returns the properties of the catalog:

{
"catalogVersion": 3,
"defaultCategoryForProducts": null,
"baseCatalog": {
"catalogVersion": 2,
"defaultCategoryForProducts": {
"repositoryId": "cat40013"
},
"rootNavigationCategory": {
"repositoryId": "rootCategory"
},
"displayName": "European Main Catalog",
"repositoryId": "catEuro",
"rootCategories": [
{
"repositoryId": "nonNavigableCategory"
},
{
"repositoryId": "rootCategory"
}
],
"id": "catEuro"
},
"displayName": "Spain",
"repositoryId": "catSpain",
"rootCategories": [],
"links": [
{
"rel": "self",
"href": "[Link]
}
],
"id": "catSpain"
}

7-6
 Chapter 7
Work with filtered catalogs

After creating a catalog, you must publish your changes to make it available to use on your
sites. See Publish Changes for more information.

Understand product membership in filtered catalogs

The updateProductMembership endpoint enables and disables membership of products to
linked filtered catalogs. Use this endpoint to perform the following tasks:
• Specify products as core products, which will automatically become members of all linked
filtered catalogs unless explicitly excluded. Whenever a new filtered catalog is created, it
will automatically contain all its base catalog's core products.
• Exclude core products from specific filtered catalogs.
• Include products that are not core products in specific filtered catalogs.
The updateProductMembership endpoint's properties specify how products are assigned to
filtered catalogs.
• catalogId is an optional property that specifies a catalog context for the request. Only
filtered catalogs that are linked to the specified can be updated by the request.
• coreProduct is a Boolean that specifies whether products are core products. If the value
of this property is null, the existing core-product status of the products will not change.
• filteredCatalogs is a list of filtered catalog IDs that will include or exclude the products,
depending on the products' coreProduct values.
• enableMembership is a Boolean that adds or removes products to the catalogs specified
by filteredCatalogs. If the request does not include the catalogId property, then the
catalogs specified by this property will explicitly replace existing values and will be treated
as inclusive or exclusive depending on whether a product is a core product. If the request
does include the catalogId property, then only the filtered catalogs linked to that catalog
are replaced. Other filtered catalogs that contain the product remain unchanged.
The following sample adds camera_1 and camcorder_1 to the filtered catalogs
myFilteredView1 and myFilteredView3. These products are not core products.

POST /ccadmin/v1/products/membership HTTP/1.1

Authorization: Bearer <access_token>
Content-Type: application/json

{
"filteredCatalogs":[
"myFilteredView1",
"myFilteredView3"
],
"enableMembership":true,
"products":[
"camera_1",
"camcorder_1"
],
"coreProduct":false
}

7-7
 Chapter 7
Work with legacy catalogs

Work with legacy catalogs

Legacy catalogs are a type of secondary catalogs that provide custom views into the
Product Catalog.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

As the name implies, legacy catalogs are an older style of Commerce catalog.
Release 21A of Commerce includes a new type of secondary catalog called a filtered
catalog. To learn how and why to use filtered catalogs to provide views into your
Product Catalog, see Work with filtered catalogs.
By default, Commerce includes a single catalog called Product Catalog. Legacy
catalogs are secondary catalogs that provide custom views into the Product Catalog.
Unlike independent catalogs, which can contain different collections and products,
legacy catalogs reference only products and collections that are already in the Product
Catalog.
You must use the Admin API (see Create legacy catalogs) to create new legacy
catalogs, but you can edit and delete them in the administration interface (see Edit and
delete legacy catalogs). You cannot convert a legacy catalog to an independent
catalog.
You can assign legacy catalogs to sites or, if your store supports account-based
commerce, to business accounts. You assign legacy catalogs in the same way you
assign independent catalogs. See Create or update an account contract to learn how
to assign a catalog to a business account. See Enter basic store information to learn
how to assign a catalog to a site.
This section includes the following topics:
• Understand legacy catalog structure
• Edit and delete legacy catalogs

Understand legacy catalog structure

In a Commerce instance that supports legacy catalogs, there are a number of tasks
that you can perform only in the Product Catalog:
• View details for a product or a collection.
• Create a new product or collection.
• Edit or delete an existing product or collection.
• Rearrange products in a collection or rearrange collection hierarchy.
• Access the following options from the Manage Catalogs menu: Product Types,
Price Groups, Inventory, and Upload Media.
Any changes you make in the Product Catalog are automatically applied to all legacy
catalogs that include the items that were changed. For example, if you update the
Product Catalog by adding a new product to a collection that is part of a catalog
associated with one of your country stores, the new product automatically appears in
that legacy catalog. Remember that you must publish any changes you make to
catalogs before they will appear on your stores.
Commerce does not index legacy catalogs for storefront search.

7-8
 Chapter 7
Create legacy catalogs

Edit and delete legacy catalogs

Although you must use the Admin API to create new legacy catalogs, you can edit and delete
them on the Catalog page in the administration interface. See Create legacy catalogs for
more information about creating these catalogs.
You can change a legacy catalog’s name and associated collections, but you cannot change
its ID. You can delete a catalog that is not associated with any sites or accounts. You cannot
delete the Product Catalog.
To edit or delete a legacy catalog:
1. Select the catalog to edit or delete in one of the following ways:
• On the Catalog page, select a catalog from the drop-down list at the top of the
catalog page to display the catalog.
• On the Catalog page, click the Manage Catalogs button and select All Catalogs.
Click the name of the catalog you want to edit.
2. To edit the catalog, click Edit Catalog, then change the catalog name or its collections.
Click Save when you finish making changes.
3. To delete the catalog, click Edit Catalog, then click the Delete button.
If the catalog is already associated with accounts or sites, you must first remove it from
all accounts or sites before you can delete it. See Work with account contracts for
information about removing a catalog from an account. See Configure Sites for
information about associating catalogs with sites.

Create legacy catalogs

The administration interface supports creating independent catalogs only.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

If you want to create legacy catalogs, you must use the Admin API. You can then edit these
catalogs using either the Admin API or the administration interface.
This section explains how to create legacy catalogs using the Admin API. For information
about editing legacy catalogs in the administration interface, see Work with legacy catalogs.
For additional information about creating and editing legacy catalogs using the Admin API,
see the REST API documentation in the Oracle Help Center.
Note: You can also create new legacy catalogs by using the CSV import feature. However,
you must first use the API to enable support for them. See Enable support for legacy catalogs
for more information. See Import catalog items and inventory to learn how to create legacy
catalogs by importing.

Enable support for legacy catalogs

Before you can create legacy catalogs, you must enable support for creating them. To do this,
you use the saveAdminConfiguration endpoint in the Admin API to set the value of the
supportVersion1Catalogs property. If your Commerce environment has any legacy catalogs,
the value of this property defaults to true, and an error is returned if you attempt to set it to
false. If your Commerce environment does not have any legacy catalogs, the value of this

7-9
 Chapter 7
Create legacy catalogs

property defaults to false, but you are free to change the value to true. The following
example enables support for legacy catalogs:

PUT /ccadmin/v1/merchant/adminConfiguration HTTP/1.1

Authorization: Bearer <access_token>
Content-Type: application/json

{
"supportVersion1Catalogs": true
}

Create a legacy catalog

To create a catalog, you can use the createCatalog endpoint in the Admin API. The
value of the supportVersion1Catalogs property determines whether an independent
catalog or a legacy catalog is created:
• If supportVersion1Catalogs is true, the createCatalog endpoint creates a legacy
catalog by default. You can override the default behavior and create an
independent catalog by setting the value of the catalogVersion property to 2.
• If supportVersion1Catalogs is false, the createCatalog endpoint can create only
independent catalogs. If you attempt to set the value of the catalogVersion to 1 to
create a legacy catalog, the call returns an error.
The following example uses the createCatalog endpoint to create a legacy catalog:

POST /ccadmin/v1/catalogs HTTP/1.1

Content-Type: application/json
x-ccasset-language: en

{
"catalogVersion": 1,
"defaultCategoryForProducts": "cat88975",
"categoryIds": [
"cat40013"
],
"catalogId": "catalogGroceries",
"displayName": "Groceries"
}

The response returns the properties of the catalog:

{
"catalogVersion": 1,
"defaultCategoryForProducts": "cat88975",
"rootNavigationCategory": {
"repositoryId": "rootCategory"
},
"displayName": "Groceries",
"repositoryId": "catalogGroceries",
"rootCategories": [
{
"repositoryId": "cat40013"
}

7-10
 Chapter 7
Associate catalogs with sites or accounts

],
"links": [
{
"rel": "self",
"href": "[Link]
}
],
"id": "catalogGroceries"
}

After creating a catalog, you must publish your changes to make it available to use on your
sites. See Publish Changes for more information.

Associate catalogs with sites or accounts

Once you have created and published a catalog, it is ready to be associated with one or more
sites. If your Commerce environment supports account-based commerce, you can also
associate published catalogs with accounts.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You can assign both independent and legacy catalogs to sites and accounts. See Understand
catalogs for information about the differences between independent and legacy catalogs.
See Configure Sites for information about creating a new site and associating a default
catalog with it. See Work with account contracts for information about associating a catalog
with an account.

Edit catalog items without publishing

Direct catalog editing allows you to update your live catalog and web site without running
through publishing steps.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This feature is not designed to be turned on and off. We recommend you choose the
publishing strategy that makes sense for your business based on a number of factors,
including how large your catalog is and its source, how often you will need to make changes
to it (high frequency/volume of publishes), and the organization of your team.
By default, when you create or modify catalog items, the changes you make must be
published before they take effect. However, you can optionally configure Commerce so that
you can make changes to the following catalog items directly on the storefront without
publishing:
• Catalogs (not including catalog media)
• Product types
• Collections
• Products and add-on products
• SKU and SKU bundles

7-11
 Chapter 7
Edit catalog items without publishing

Publishing catalog changes works well for many merchants, particularly those that
change their catalogs relatively infrequently. Some merchants, however, have a large
number of products and update their catalogs frequently, in some cases updating them
every day or multiple times a day. For these merchants, Commerce provides the ability
to make catalog changes available on the storefront immediately, bypassing the
publishing process.
Enabling the direct catalog editing feature means:
• You can immediately display any changes without the need to publish.
• You can directly push your entire catalog data to production by avoiding the
publishing step. This is particularly useful when changes to products, collections,
or SKUs occur frequently.
• Search content updates run every 15 minutes to ensure the search index is up-to-
date.
Consider direct catalog editing if you are getting catalog data from an external system,
such as a supplier or a PIM, and passing that data through without requiring users to
make changes to that catalog data; or if you frequently publish a large number of items
or assets. You may also want to consider it if you are concerned about publishing
times, which increase when changes affect a large number of assets, and/or when
there is a high volume of product catalog changes.
You might also want to use direct editing if you are concerned about lockout, since
during a publishing event, users cannot work with administration interface tools. This
feature may also be helpful if you have distributed teams, with a number of individuals
publishing throughout the day and/or from multiple time zones.
Direct catalog editing is not designed to be turned on and off, and as such, you should
consider this process to be part of your environment. Because this feature is working
with a live production site, you should carefully consider whether direct catalog editing
is something that you want to enable.

Understand additional considerations when using direct catalog editing

Choosing to use direct catalog editing and bypassing the publishing process comes
with some trade-offs, including:
• You will not be able to preview any changes you make before they are in
production.
• Search indexing runs every fifteen minutes, which might result in a lag between
when changes go live and when that changed is indexed and appears in any
search or navigation results.
• Product recommendations do not immediately reflect direct catalog edits. Instead,
the recommendations service exports the catalog daily in order to generate
product recommendations, which can mean that the products returned may be up
to 24 hours old.
Important: Enabling direct catalog editing automatically enables direct price editing.
For more information about direct price editing, see Update prices without publishing.
(You can choose to use direct price editing on its own, even if you choose to use the
default publishing process for catalog changes.)
Since direct catalog editing is not designed to be turned on and off, you should
consider whether or not it makes sense to use this feature, ideally during your site
implementation as you are thinking through your business processes. Because this

7-12
 Chapter 7
Edit catalog items without publishing

feature is working with a live production site, you should carefully consider whether direct
catalog editing is something that you want to enable.

Perform prerequisite checks

There are a few things that you should check before enabling and disabling direct catalog
editing:
• There are no items in the search indexing queue.
• If your stores have any unpublished catalog or price changes, you must publish them
before attempting to enable direct catalog editing. Additionally, make sure no imports or
publishing events are happening while you are enabling direct catalog editing.
• Your site's URL patterns are using IDs to specify products and collections.
Note that the updateDirectEditConfiguration endpoint will perform the necessary
validations and return the appropriate errors.

Update your catalog without publishing

To update your catalog directly without publishing, enable direct catalog editing using the
updateDirectEditConfiguration endpoint.

For example:

PUT /ccadmin/v1/merchant/directEdit/catalog
{
"enable" : true
}

Use direct catalog editing

If you create or modify a catalog item when direct catalog editing is enabled, (using the
administration interface, an endpoint, or an import process) the changes you make are
available on the storefront without publishing; they do not appear in the list of changes that
are returned by REST endpoints or appear in the Publishing page of the administration
interface (although the data that is live on the site is reflected and editable in the
administration interface tool elsewhere).
When you publish changes, Commerce initiates an indexing operation so the search index is
updated to reflect the changes. However, with direct catalog editing, catalog items on the
production server can be changed without publishing, which means catalog items in the index
may become out of date. See Manage Search Settings for more information.
To ensure the index is kept up-to-date, enabling direct catalog editing enables a schedule that
performs incremental indexing every 15 minutes. Performing a publishing operation does not
trigger an index when direct catalog editing is enabled. However, if you have already used the
setSearchPartialSchedule endpoint in the Search Data and Indexing API to set up a
different incremental indexing schedule, that schedule will remain in place instead.
Note: When bulk import is running, you will notice that storefront performance is slower
because bulk import requires continual purging and invalidation of the storefront cache. Refer
to Perform Bulk Export and Import for additional information.
Disable direct catalog editing
Before disabling direct catalog edit, refer to Perform prerequisite checks for more information.

7-13
 Chapter 7
Create and edit product types

You can disable direct catalog editing by using the updateDirectEditConfiguration

endpoint to set the enable property back to false. Doing so initiates a full publishing
process.
It is worth noting, however, that you should decide which mode makes most sense for
your store, and continue to use that mode unless your business needs change. The
feature is not designed to be turned on and off frequently. Disabling direct catalog
editing may cause a considerable delay, because Commerce must then synchronize
your publishing server with the catalog on your production server.
After disabling direct catalog editing, direct price editing remains enabled, as does
incremental indexing. If you then turn off direct price editing, incremental indexing is
canceled.
However, if you used the setSearchPartialSchedule endpoint to create a different
incremental indexing schedule, disabling catalog editing does not cancel that schedule
unless you have set the parseString parameter to "* * * * * 0,15,30,45".

Understand scheduled site map generation

Site maps are generated nightly and direct catalog editing does not modify that
behavior.
Note: All site maps are updated, even if your catalog updates only impact a small
number of your overall site maps.

Create and edit product types

Product types are templates for products you add to your catalog.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Product types contain properties that describe a product, such as fabric type or
available colors. They can also optionally contain properties that request shopper
input, such as the message to include with a gift or the initials to use for a monogram.
When a merchandiser creates a new product, the properties available to fill out
depend on the product type they select.

Understand the base product type

The built-in base product type contains basic product and SKU properties that apply to
all products and SKUs in your catalog. Custom product types automatically inherit all
the base product type’s properties.
The following table describes the default product properties for the base product type:

Property Description
Name (required) Short, descriptive name that identifies the
product.
Product ID (required) The ID that identifies the product internally.
Each product ID must be unique within your
catalog.
Description A short description to display with the product.
Brand The name of the manufacturer.

7-14
 Chapter 7
Create and edit product types

Property Description
List Price (required) Default price of the product before any
discounts or promotions.
If your store supports more than one currency,
enter a list price for each price group shown.
See Configure Price Groups for more
information.
Sale Price Sale price of the product.
If your store supports more than one currency,
enter a sale price for each price group shown.
See Configure Price Groups for more
information.
Shipping Surcharge Additional shipping charges that apply to the
product because of size, weight, or special
handling.
If your store supports more than one currency,
enter a shipping surcharge for each price
group shown. See Configure Price Groups for
more information.
Product Tax Code A tax code to assign to the product that allows
your tax processor to make the appropriate tax
calculations. For more information, see
Configure Tax Processing.
Long Description Detailed descriptive text to display with the
product. The long description is created with
an HTML editor called CKEditor that you can
use to edit and apply rich-text formatting.
Active Specifies whether the product is displayed on
your store and in search results. By default,
the Active option is not selected.
Discountable Specifies whether the product can be
discounted by Commerce promotions. By
default, the Discountable option is selected.
For more information, see Understand
promotion targets.

7-15
 Chapter 7
Create and edit product types

Property Description
Not For Individual Sale Specifies whether the product can be
purchased only as part of a complex,
customizable product. For example, if your
store sells laptops, some of the individual
components such as motherboards or
graphics cards may not be for sale as
individual products but can be sold as
component parts of a customized product.
Products marked as not for individual sale do
not appear in collections shoppers browse on
your store or in search results.
Unlike inactive products, which shoppers
cannot purchase at all, products marked as
not for individual sale can be purchased, but
only as a component of a customizable
product.
By default, the Not For Individual Sale option is
not selected.
Note: To create customizable products, you
must have an active Oracle CPQ account.
Not Returnable Indicates that the storefront elements allowing
shoppers to initiate a return from their order
history should not be active for this product.
Exclude from XML Sitemap Excludes selected products from the product
sitemap.
The XML sitemap is an index of page URLs on
your site that is available for crawling by
search engines. It helps search engines to
crawl your site more intelligently.
Assetable Indicates that the product should be tracked as
an asset.
Prior to checkout, Commerce will require
shoppers to assign customer, service, and
billing account details for this product, along
with a billing profile. Select this property only
for products sold as services or subscriptions
such as broadband, wireless, or magazine
subscriptions.
Shippable Specifies that the product is a physical item
that can be shipped. By default, the Shippable
option is selected. Deselect it if the product is
something that will not be shipped, such as a
service.
Arrival Date Stock arrival date for the product.
Stock arrival date for the product. By default,
this property is not displayed on the storefront
(though it is available to be added to custom
widgets you create), and does not control
whether a product can be purchased.
Shoppers can purchase an active product with
active SKUs in stock, regardless of the Arrival
Date, even if that date is in the future.
Height, Length, Width, and Weight Specifies the physical dimensions of a product.

7-16
 Chapter 7
Create and edit product types

Property Description
Order Limit The maximum number of this product that can
be purchased per order.

The following table describes the default SKU properties for the base product type.

Property Description
Name Short, descriptive name that identifies the SKU. By
default, the SKU inherits the name of its parent
product.
SKU ID The ID that identifies the SKU internally. Each
SKU ID must be unique within a product.
Active Specifies whether the SKU is displayed on your
store and in search results when its parent product
is active. By default, the Active option is selected.
Discountable Specifies whether the SKU can be discounted by
Commerce promotions. By default, the
Discountable option is selected. For more
information, see Understand promotion targets.

Edit the base product type

You can add new properties to the base product type and make some changes to its default
properties. You cannot remove any of the default type or SKU properties, though you can do
the following:
• Mark some of them as not required so that merchandisers can ignore them when creating
new products. (The product’s Name, ID, and List Price properties are always required, as
is the SKU ID property.)
• Mark them as Internal-Only so that they cannot appear on the storefront.
To edit product properties in the base product type:
1. On the Catalog page, click the Manage Catalogs button and select Product Types.
2. Click Base Product to display its type properties.
3. To add a new product property, click Add Property and select Standard or Shopper
Input.
• Standard specifies properties whose values you provide when creating products.
• Shopper Input specifies properties whose values shoppers provide when purchasing
a product on your store. For example, initials for a monogram or a message to
accompany gift wrapping.
See Create custom product types for details about how to add a new property.
4. To edit an existing property, click its Edit button.
You cannot change a default property’s ID. You can make optional properties required,
but you cannot make required properties optional.
See Create custom product types for details about property settings.
5. Click Done when you finish adding and editing properties.
To add or edit SKU properties in the base product type:

7-17
 Chapter 7
Create and edit product types

1. On the Catalog page, click the Manage Catalogs button and select Product
Types.
2. Click Base Product to display its type properties.
3. Click the SKU Properties tab.

Understand custom product types

In addition to inheriting all the product properties from the base product type, custom
product types let you provide product, SKU, and variant properties for different kinds of
products.
• Standard product properties let you add information specific to a particular kind of
product. For example, suppose your store carries a large inventory of cameras.
You might want to create a custom product type called Camera that includes type
properties like effective pixels and exposure control.
Standard product property values can also be used as search terms and facets on
your store. For more information, see Create custom product types.
• Shopper input product properties let you capture information from shoppers for a
particular kind of product. For example, shoppers can enter initials for a monogram
or a message to include in a card with gift wrapping. Shopper input properties can
be displayed on the storefront but are not used as search terms and facets.
Shopper input properties can be optional or required. For example, when a
shopper selects gift wrapping they can include an optional gift message, but when
a shopper selects monogramming, they must supply the letters that will be
monogrammed on the main product.
See Support add-on products for an example of incorporating a custom shopper
input property into a widget so shoppers can use it on the storefront.
• SKU properties let you add information specific to a SKU. For example, you could
create custom SKU properties that hold UPC codes or IDs that represent SKUs in
an external order management system.
SKU property values can also be used as search terms and facets on your store.
For more information, see Create custom product types.
• Variant properties represent options you can combine to create SKUs. For
example, if a shirt is available in three sizes and two colors, size and color are its
variant properties.
Variant property values can also drive image display on your store’s product
details and category pages. Select one variant property per product that gets
images assigned to each of its values. For example, suppose a shirt called Cotton
Tee is available in three colors, red, blue, and green. You can assign separate
images to each color value. When a shopper navigates to the shirt’s product
details page and selects the color green, the main image changes to the green
shirt.
You can also display style-based products on category pages. That is, images for
each value of the selected variant appear as separate products on your store.
Continuing with the shirt example, suppose the shirt is part of the Tops & Tees
category. When a shopper navigates to Tops & Tees, the shirt appears three times
on the page, once in each of the available colors.
For more information, see Create custom product types.

Create custom product types

To create a custom product type:

7-18
 Chapter 7
Create and edit product types

1. On the Catalog page, click the Manage Catalogs button and select Product Types.
2. Click New Custom Type.
3. Enter a name for the new product type and click Save.
You can now add product, SKU, and variant properties to the new product type.
To add standard product properties to a custom product type:
1. On the product type’s Product Properties tab, click Add Property and select Standard.
2. Select a property type and enter values to define it.
The property type you select controls the type of editor merchandisers see when they
create products using this new type. For more information, see Property types.
3. Click Save.
4. Repeat steps 1 through 3 for each new standard product property you want to add to the
product type. When you are finished, click Done.
To add shopper input properties to a custom product type:
1. On the product type’s Product Properties tab, click Add Property and select Shopper
Input.
2. Select a property type and enter
The property type you select controls the type of editor shoppers see on your store. . For
more information, see Property types.
3. Click Save.
4. Repeat steps 1 through 3 for each new standard product property you want to add to the
product type. When you are finished, click Done.
To add SKU properties to a custom product type:
1. On the product type’s SKU Properties tab, click Add Property.
2. Select a property type and enter values to define it.
The property type you select controls the type of editor merchandisers see when they
create products using this new type. For more information, see Property types.
3. Click Save.
4. Repeat steps 1 through 3 for each new SKU property you want to add to the product
type. When you are finished, click Done.
To add variant properties to a custom product type:
1. On the product type’s Variant Properties tab, click Add Property.
2. Enter a name, ID, and values for the property. Press the ENTER key after you type each
property value.
For example, to add color variants to a property type, you could enter the following:
Name: Color
ID: color
Values: Poppy, Navy, Charcoal, White
Tip: You can drag values to reorder them. The order values appear in here is their default
order on the product detail page on your store, though you can change the order for
individual products. See Sort variant values on the product details page for more
information.
3. Click Save.

7-19
 Chapter 7
Create and edit product types

4. Repeat steps 1 through 3 for each new variant property you want to add. When
you are finished, click Done.
You can configure how images are displayed for property values of one variant per
product type. Select a variant whose properties look different in images, such as color.
To configure image display for a variant property’s values:
1. On the product type’s Variant Properties tab, click Edit for the property you want
to use.
2. Under display properties, select Allow product images at variant property value
level.
This allows you to assign a different image to each of the variant’s values.
3. If you also want to display images for each value separately on collections pages,
select Display product entries in product listing by these property values.
Important: Once you save these options, you cannot change them.
4. Click Save.
See Add images to products for information about how to assign images to the values
on a product-by-product basis.

Delete custom product types

You can delete custom product types with the Admin API. You cannot delete the base
product type. You cannot delete a product type that is being used by products in your
catalog. For details about the Commerce REST API endpoints, see Use the REST
APIs.
Delete a custom product type by specifying its ID. Send a GET request to the/
ccadmin/v1/productTypes endpoint to get a list of all custom product types in your
Commerce instance. For example:
The following is a sample response for a productTypes request:

{
"items":[
{
"displayName":"test product type",
"id":"testproducttype"
},
{
"displayName":"New Product Type",
"id":"NewProductType"
}
]
}

Once you have the ID of the custom product type you want to delete, send a DELETE
request to the/ccadmin/v1/productTypes/{id} endpoint to deleted the specified
product type. The following sample request body removes the custom product type
NewProductType a Commerce instance:

{"id":"NewPropertyType"}

7-20
 Chapter 7
Create and edit product types

Property types
The following table describes the properties you can add to a product type or SKU type.

Property type Allows the merchandiser to enter

Short text A single line of unformatted text.
Text area One or more paragraphs of unformatted text. This
is also known as a long text property. For details
about this property type, see Add long text
properties to products and SKUs.
Rich text One or more paragraphs of formatted text.
Note: A rich text property can have a default value
of no more than 255 characters. However, if you
import or manually enter the value, it can have
multiple paragraphs, each with more than 255
characters.
Number A numeric value.
Check box A single true/false property.
Date A date and time property with a calendar picker.
Selection list A list property that allows a single selection from a
specified set of values.

The following table describes the settings for each standard product or SKU property:

Setting Description
Label (required) The label that appears above the property editor in
the product dialog.
Property ID (required) The ID that identifies the property internally.
Each property ID must be unique within your
catalog, although the administration interface does
not always prevent you from creating multiple
properties with the same ID. If a property in the
base product type and a custom property in a
custom product type have the same property ID,
the value of the property in the base product type
always overwrites the value of the property in the
custom product type.
Default Value A value that is pre-populated in the property editor.
Properties that are required must have default
values.
Values For a Selection List property, the set of strings to
display in the list. You must add at least one string.
Press Enter after you finish typing each string to
add it to the Values field.
Required Specifies whether a property must be set before a
merchandiser can save a product. By default,
properties are not required.
Translatable Specifies whether a short-text or rich-text property
can be translated. By default, properties are not
translatable.
If you select this option, you cannot change it later.

7-21
 Chapter 7
Create and edit product types

Setting Description
Display Properties Select Visible in Storefront if you want to be able
to display the property on your store. This is the
default setting for all properties.
Select Internal Only if you do not want the
property to appear on your storefront.
Note that shopper input properties cannot be
Internal Only.
Allow property to be searched Allows shoppers to search on values entered for
properties.
This setting is available for short text and number
properties.
You must also add the property to the searchable
field ranking to make it searchable. See Add fields
to the searchable field ranking list.
Allow property to be search facet Allows shoppers to use the property as a
refinement when filtering search results.
This setting is available for short text and number
properties.
Allow property to be a multi-select search facet Allows shoppers to use the property as a
refinement when making multiple selections to
filter search results. For example, shoppers could
filter results by selecting several brands.
This setting is available for short text and number
properties.

The following table describes the settings for each shopper input product property:

Setting Description
Label (required) The label that appears above the property
editor on your store’s pages.
Property ID (required) The ID that identifies the property internally.
Each property ID must be unique within a
product type.
Shopper Input Prompt Helper text that appears with the property
editor on your store’s pages.
Default Value A value that is pre-populated in the property
editor. Properties that are required must have
default values.
Values For a Selection List property, the set of strings
to display in the list. You must add at least one
string. Press Enter after you finish typing each
string to add it to the Values field.
Required for Shopper Specifies whether a property must be set
before a shopper can complete the purchase.
By default, properties are not required.

Add long text properties to products and SKUs

Long text properties (called Text Area in the administration interface Property Types
dialog) let you store a large amount of plain unformatted text, such as content in CSV,
JSON, or new-line-separated list formats.

7-22
 Chapter 7
Create and work with products

No long text properties are available by default, but you can create and add long text
properties to any Commerce product type or SKU type, using either the administration
interface or the Admin API.
To create a long text property in the administration interface, follow the instructions in Create
custom product types. To create a long text property with the Admin API, use the
createProductTypeSpecification endpoint for product types and the createSkuProperty
endpoint for SKU types. See Learn about the APIs for information about accessing the REST
API documentation.

Create and work with products

A product is a navigational end-point in your catalog, for example, a camera or a pair of
shoes.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Once you have defined product types as described in Create and edit product types, you can
use those types to create or import new products. This section describes how to work with
products on the Commerce Catalog page. To learn how to import products into your catalog,
see Import and Export Catalog Items and Inventory.
This section includes the following topics:
• Create products
• Activate and deactivate products
• Delete products

Create products
If a collection is selected when you create a product, the new product is automatically created
in that collection. Otherwise, it is created in Unassigned Products. If the collection where you
create a product is linked to other parents, the product will appear in all locations the
collection is linked to. You cannot create products in the Storefront Navigation or Non-
Navigable root collections. See Organize Products in Collections for more information.
This section describes how to create a new product. See Link and unlink collections and
products to learn how to link an existing product to a collection.
To create a new product:
1. On the Catalog page, click the New Product button and select New from the menu that
appears.
2. Select a product type and click Select.
3. Enter values for the product’s properties.
The properties you see depend on the product type you selected.
See Understand the base product type for information about the default properties
available to all products.
4. Click Create.
Now you can create SKUs by combining the properties you entered. See Create and work
with SKUs for more information. You can also add images. See Add images to products for
more information.

7-23
 Chapter 7
Find products in catalogs

Activate and deactivate products

By default, a newly-created product is not active, which means that none of the
product’s SKUs are displayed on your store. You might want to deactivate a product if
inventory is low or if the product will soon be discontinued.
Deactivating a product prevents it from appearing on your store or in search results but
does not remove it from your environment. (See Delete products for information about
permanently removing a product.) If you deactivate a product that is linked to more
than one parent, Commerce deactivates it in all locations.
To deactivate a product:
1. On the Catalog page, open the product you want to deactivate.
2. On the General tab of the product details page, uncheck the Active setting and
click Save.

Delete products
Deleting a product permanently removes the product and all its associated SKUs from
Commerce. All price lists that included prices for the product’s SKUs are automatically
updated. If you delete a product that is linked to more than one parent, Commerce
deletes it in all locations.
Once you delete a product, you cannot retrieve it. Deleting a product might also affect
orders and reports that include the product’s SKUs. An alternative to deleting a product
is marking it as inactive so that it is no longer displayed. See Activate and deactivate
products for more information.
Important: Deleting assets, such as products, catalogs, shipping methods, etc., can
result in discrepancies in your system, which may produce errors. It is recommended
that you disable assets instead of deleting.
To delete a product:
1. On the Catalog page, select the product whose SKUs you want to delete.
2. On the General tab, select SKUs and click Delete Selected SKUs.
3. Confirm that you want to delete the SKUs.

Find products in catalogs

You can perform custom, rule-based searches to quickly find products in collections
and catalogs.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The Catalog page in the administration interface always opens in Search Products
view, which is empty until you perform a search or select a collection that contains
products.
You can perform a simple search by entering a product name or product ID into the
search field at the top of the page, or you can create a rule that searches using other
product properties, including custom properties. By default, the search returns results
from all catalogs, though you can filter the results so only products from the current
catalog are displayed.

7-24
 Chapter 7
Find products in catalogs

To find products in your catalogs:

1. On the Catalog page, select Search Products.
2. (Optional) To search only a specific collection, select it in the catalog's collection
hierarchy. You can also select Unassigned Products and Unassigned Collections.
3. In the search box, type or paste full or partial product names, IDs, or both.
• Separate multiple entries with commas.
• You can mix names and IDs in the same search. For example, entering the following
search terms returns all products whose names and IDs include the word glass as
well as the item whose ID is xprod2162:
glass, xprod2162
• If you enter just a comma, the search will not start, even if your catalog includes
products whose names include commas.
• There is a limit of 1000 characters and 200 search terms, whichever comes first. If
there are more than 200 search terms, all terms past 200 are ignored. If there are
duplicate IDs, any ID past the first is ignored.
4. To search on properties other than Product Name and Product ID, create a rule. See
Create rules to search for products for more information.

Create rules to search for products

A rule automatically finds products based on product properties in a product type you specify.
You cannot save search rules. If you navigate away from the Catalog page, any search rules
you created will not persist when you return.
To create a search rule, follow these steps:
1. On the Catalog page, click Search Products and then click the Custom Search icon
next to the search text box.
2. Select a product type to use from the Product Types list, then click the Create Rule
button.
You can select only one product type per rule.
3. Select a property from the drop-down list in the rule. The available properties depend on
the product type you selected in the previous step. You can select only one property per
rule.
4. Select an operator that links the property to a value that you will specify in the next step.
The operators you see depend on the type of property you selected. See Create and edit
product types for details about product types and the types of properties they can
contain.
5. Select or enter a value for the property.
For some values, such as parent collections, Commerce displays a list for you to choose
from. For others, such as Availability Date or Brand, you must type in a value. The rule
editor does not validate any text, numeric, or date values you type.
6. If you create more than one rule, select one of the following options from the Match list to
specify how the rules behave together. You can select one option only for the entire set of
rules.
• Any Rules: If a product matches any rule in the set, it is returned in the search
results.

7-25
 Chapter 7
Create and work with SKUs

• All Rules: (default) If a product matches all the rules in the set, it is returned in
the search results.
7. Click Search.

Example: Search for missing information

The following example shows how to find all the products with no images that are
currently displayed on your store so you can quickly fix them by adding images. In this
example, you will create two rules that are both evaluated together. One rule searches
for all products that do not have product images and the other searches for all active
products.
To find active products with no images, follow these instructions:
1. On the Catalog page, click Search Products and then click the Custom Search
icon.
2. Select All from the Product Types list and All Rules from the Match list.
3. Click the Add Rule button.
4. In the new rule, select Product Images from the Properties list and Does Not
Exist from the Operators list.
5. Click the Add Rule button again to add a second rule.
You'll see that the second rule starts with AND because you selected All Rules in
step 2.
6. In the second rule, select Active from the Properties list and True from the
Operators list.
7. Click Search when you finish creating the rules.
The search results will display all the products without images that are active on your
store. You can click a product in the results to open its details pane, where you can
add images to its Media tab.

Create and work with SKUs

A SKU (stock keeping unit) represents a purchasable instance of a product on your
store.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Customers do not actually purchase products, they purchase SKUs. A product can
have several different SKUs associated with it, representing varieties, sizes, and
colors. For example, the product Sundress, which is available in two different colors
and five sizes, has ten associated SKUs, one for each size/color combination. Each
product must have at least one SKU.
You create SKUs by combining a product’s variant properties. Each product must have
at least one SKU for customers to purchase and for Commerce to index for searching.
You create SKUs by combining a product’s variant properties. If a product was created
from a product type that has no variant properties, you must still create a single SKU
for it.
This section includes the following topics:
• Create SKUs

7-26
 Chapter 7
Create and work with SKUs

• Deactivate SKUs
• Delete SKUs
• Sort variant values on the product details page
• Create SKU bundles

Create SKUs
To create a SKU for a product with no variant properties:
1. On the Catalog page, select the product for which you want to create the SKU.
2. Click the SKUs tab.
3. Select the SKU and add an ID and optionally, a name, for it.
4. Click Create.
To create SKUs for a product with variant properties:
1. On the Catalog page, select the product for which you want to create SKUs.
Note: You cannot add variant properties and create multiple SKUs for products created
with the base product type. For more information, see Create and edit product types.
2. On the SKUs tab, select values for each variant property.
Click the variant to see a full list of available values. Select a value from the list. To
narrow the list, begin typing some text. The filter matches characters that you type
wherever they appear in the value, not just at the beginning. Usually, as you type more
characters, there are fewer matches.
3. When you have selected all the variant properties you want to combine into SKUs, click
Display Combinations.
4. Select each SKU you want to assign to the product and add an ID and optionally, a
name, for each SKU you select. SKU IDs are required and each must be unique within
the product.
5. Click Create.
If a SKU’s product was created with a product type that includes custom SKU properties, you
can edit them once you have created the SKUs.
To edit SKU property values:
1. On the Catalog page, select the product whose SKUs you want to update.
2. On the SKUs tab, click the SKU ID of the SKU to update.
3. Click the SKU Properties tab and edit the SKU properties.
If the SKU’s parent product was created from a custom product type, the name of the tab
will be the name of the product type instead of SKU Properties.
4. Click Save.
By default, SKUs inherit the list and sale prices of their parent product. You can override
these prices on a per-SKU basis. To change the price for a SKU:
1. On the Catalog page, select the product whose SKUs you want to update.
2. On the SKUs tab, click the SKU ID of the SKU to update.
3. Click the SKU’s Price Groups tab and then click the Edit icon.
4. Enter a new list price or sale price value.

7-27
 Chapter 7
Create and work with SKUs

5. Click Save.

Deactivate SKUs
By default, all a product’s SKUs are active, which means that when the product is
active, all SKUs are displayed on your store. You might want to deactivate a SKU if
inventory is low or if the SKU contains a variant that will soon be discontinued, like a
seasonal color.
Deactivating a SKU prevents it from appearing on your store or in search results but
does not remove it from the product. (See Delete SKUs for information about
permanently removing a SKU from a product.) If you deactivate all a product’s SKUs
but do not deactivate the product, the product is still visible and appears in search
results but shoppers cannot buy it. See Create and work with products for information
about deactivating a product.
To deactivate a SKU:
1. On the Catalog page, select the product whose SKUs you want to deactivate.
2. On the SKUs tab, click the ID of a SKU.
3. On the SKU details page, uncheck the Active setting and click Save.

Delete SKUs
Deleting a SKU permanently removes it from a product. If you want to keep the SKU
but no longer display it, mark it as inactive. See Delete SKUs for more information.
To remove SKUs from a product:
1. On the Catalog page, select the product whose SKUs you want to delete.
2. On the SKUs tab, select SKUs and click Delete Selected SKUs.
3. Confirm that you want to delete the SKUs.

Sort variant values on the product details page

By default, variant values appear on the product details page in the order specified
when you created the product type. You can override the default order for individual
products.
To reorder variant values on the product details page:
1. On the Catalog page, open the product whose variant values you want to reorder.
2. On the SKUs tab, select the name of the variant whose values you want to reorder
from the Configure Storefront Display list.
3. Reorder the values and click Update or Save.
4. Click Save to close the product.

Create SKU bundles

A SKU bundle is a single SKU that is composed of several other SKUs. SKU bundles
allow a group of items to be purchased as a single item but treated as multiple items in
order fulfillment. The SKUs that make up a bundle are always the same; a shopper
cannot customize a SKU bundle. For example, a gift basket created as a SKU bundle
always contains the same items; shoppers cannot choose the contents of the gift
basket.

7-28
 Chapter 7
Create and work with SKUs

SKUs in a bundle can be sold exclusively in the bundle, but you can also sell them
individually.
Commerce automatically sets the inventory for a SKU bundle based on available inventory of
the SKUs the bundle contains. For example, suppose a SKU bundle (SKU C) contains 1 of
SKU A and 2 of SKU B. There are 20 of SKU A and 10 of SKU B in stock. Therefore, SKU
C’s (the bundle’s) stock is 5 because that is how many bundles could successfully be
purchased given the current inventory of SKU A and SKU B. See Manage inventory for more
information.
If the SKU that serves as the bundle is set as not discountable, then the entire SKU bundle
cannot be discounted, even if some of the SKUs it contains are marked as discountable.
Similarly, if the SKU that serves as the bundle is marked as discountable, then the entire SKU
bundle can be discounted, even if some of the SKUs it contains are marked as not
discountable
Creating a SKU bundle is a three-step process:
1. Create the SKU that will serve as the bundle.
2. Add SKUs to the bundle.
3. Specify how many of each SKU the bundle contains.
The procedures that follow describe each of these steps in detail.
To create the SKU that serves as the bundle:
1. Create a product that will include the SKU bundles. See Create and work with products
for more information.
Since SKU bundles cannot be customized by shoppers, you might want to create a
product that contains a number of similar SKU bundles to offer shoppers choice. For
example, suppose you want to bundle a variety of scented votive candles into different
combinations of three. In this case, create a product called Votive Packs.
2. In the new product, create the SKUs that will serve as the bundles See Create SKUs for
more information.
Continuing with the votive candle example, create a SKU for each combination of scents
you want to sell.
To add SKUs to a SKU bundle:
1. Select a SKU and click the Bundled SKUs tab.
2. Click the Include SKUs button.
3. Select one or more SKU IDs from the list. You can filter the list by typing or pasting all or
part of a SKU ID in the SKUs box.
4. Click Add Selected.
5. Click Done when you finish adding SKUs.
To specify the number of each SKU that the bundle will contain:
1. On the Bundled SKUs tab, click the quantity for the SKU you want to edit.
2. Enter a new value and click the Save icon.
3. Click the Save button on the SKU tab when you finish updating quantities.

7-29
 Chapter 7
Create add-on products

Create add-on products

Add-on products let shoppers customize or enhance their purchases with optional
extras like monogramming, gift wrap, or warranties.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You link an add-on product to a main product so shoppers see it on the main product’s
details page and can optionally purchase it along with the main product.
If your storefront is built using Storefront Classic, you must make changes to several
storefront layouts to allow your store to support add-on products. To learn how to
display add-on products in Storefront Classic layouts, see Support add-on products. If
your storefront is built using Open Storefront Framework (OSF), you can use the
default OSF widgets that let you display add-on products in the Product, Cart,
Checkout, Order History, Order Details, and Return Details pages. These widgets are
described at the end of this topic.
Keep the following points in mind when working with add-on products:
• An add-on product is available for all the main product’s SKUs. You cannot link an
add-on product only to specific SKUs. For example, if monogramming is available
for a tote bag, you cannot specify that monogramming is available only for canvas
SKUs but not leather SKUs.
• For an add-on product with multiple SKUs, you do not have to link all the SKUs to
a main product. For example, suppose an add-on product for warranties includes
SKUs for 1-year, 2-year, and 3-year protection. It may not be appropriate to offer a
2-year or 3-year warranty on inexpensive items, so you can choose to offer only
the 1-year warranty on those items.
• Any SKUs added to an add-on product after it was added to the main product are
not automatically selected as add-ons. To add the new SKUs remove the product
as an add-on and then add it again.
• Add-on products can be products that you let shoppers buy separately, for
example, USB cables or chargers could be sold separately and could also be sold
as add-on products for phones. It does not make sense for certain types of add-
ons, like monograms and gift wrapping, to be sold on their own, but for add-on
products that can be purchased separately, the price is the same, whether the
product is purchased on its own or as an add-on to another product.
• Volume pricing is not supported for add-on products.
• When a product is discounted by a promotion, add-on products linked to are also
discounted. See Understand how add-on products affect promotions for more
information.
Follow these steps to create an add-on product:
1. Create a product type for the add-on product. This lets you add product, SKU, and
variant properties specific to each type of add-on product, such as color, style, and
text for a monogram, or length of coverage for a warranty. See Create and edit
product types for more information.
2. Create the add-on product from the product type you created in the previous step.
See Create and work with products for more information.

7-30
 Chapter 7
Create add-on products

3. Create one or more SKUs for the new product. See Create SKUs for more information.
Continuing with the monogram example, create a SKU for each combination of
monogram colors and styles you want to offer.
4. Add inventory for each SKU. See Manage inventory for more information.
Follow these steps to link an add-on product to a main product:
1. On the Catalog page, select the main product to which you want to link add-on products.
2. On the Add Ons tab, click the Include Add Ons button.
3. Select one or more products from the list. You can filter the list by typing or pasting all or
part of a product name or ID in the Add Ons box.
4. Click Add Selected.
5. Click Done when you finish adding products.
6. By default, Commerce includes all an add-on product’s SKUs, but you can remove any
that are not appropriate for the main product.
Click an add-on product to display its SKUs, then click the X icon next to a SKU to
remove it. If you remove all a product’s SKUs, Commerce automatically removes the
add-on product.
7. Click Save.

Import and export add-on products

You can use the import feature to create add-on products and link them to other products in
your catalog. See Import and Export Catalog Items and Inventory for details about how to
import and export data in Commerce.
The easiest way to format a file for importing catalogs is to start by exporting a file that you
can use as a template for items you want to add or modify. See Export catalog items for more
information about how to export data.
When you look at the exported spreadsheet, you can see that the second row displays
column headings that contain the internal names of the exported properties. The
addOnProduct column includes product IDs for the add-on products and the addOnSku column
includes SKU IDs for each SKU available for the products in the corresponding addOnProduct
cell.
Product data begins in the third row and continues for the remainder of the spreadsheet. If an
item does not have a value for a property, the corresponding cell is blank. When an add-on
product has multiple SKUs, its addOnProduct cell contains multiple entries for each product,
one for each of the SKUs and its addOnSku column contains multiple entries, one for each
available SKU. Multiple entries are separated with a| (vertical bar.
For example, suppose a product has optional monogramming. There are three
monogramming SKUs, one for each of three colors. The addOnProduct cell in the
spreadsheet might look like this:

item1:Product_19Mg|item2:Product_19Mg|item3:Product_19Mg

The addOnSku cell in the spreadsheet might look like this:

item1:Sku_19red|item2:Sku_19blu|item3:Sku_19grn

7-31
 Chapter 7
Organize products in collections

Display add-on products in Open Storefront Framework (OSF)

OSF includes default widgets that let you display add-on products on your storefront.
The product-details container widget, on the Product layout, includes a product-add-
on-items widget. This widget renders a checkbox with the add-on item name. It
includes a child component, add-on-item-details, that renders the additional details of
each add-on item.
The add-on-item-details component has two child components:
• add-on-item-shopper-input displays fields for shopper input, such as the message
to include with a gift or the initials to use for a monogram. For details about
shopper-input properties, see Create and edit product types.
• add-on-item-variant displays the list of SKUs, a shopper can select from, such as
combinations of monogram colors and styles. Each SKU is displayed with a radio
button so shoppers can select it.
When the shopper selects add-on items and clicks the product-add-to-cart button, the
selected add-on items are added to the cart along with the main product. The cart-add-
on-items widget renders the add-on items, along with details like SKUs and shopper-
input values, on the Cart, Checkout, Order Confirmation, Order History, Order Details,
and Return Details pages. On the Cart, Extended Cart, and Checkout Shipping pages,
a checkbox is displayed (and checked by default) for each add-on item. If the shopper
unchecks a checkbox, the associated add-on item and its details are removed and the
cart is repriced. (On the Checkout Review, Order History, Order Details, and Return
Details pages, the checkbox is hidden and only add-on item details are displayed.)

Organize products in collections

Collections organize your catalog into a hierarchy that provides a navigational
framework for your store.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Collections can contain both products and other collections.

Note: Commerce also supports directly linking products to independent catalogs
without adding those products to collections.

Understand collections
Collections organize your catalog into a hierarchy that provides a navigational
framework for your store. Collections can contain both products and other collections.
Each Commerce catalog includes two root collections. These collections cannot be
deleted or made children of any other collections. These are the only two root
collections a catalog can contain; you cannot create other root collections.
• Storefront Navigation is the starting point in the navigational structure of the
catalog. It contains all the catalog’s collections, products, and SKUs.
• Non-Navigable contains products and collections, like gift wrapping or
monogramming, that shoppers can buy but not browse to as part of the
hierarchical catalog on your store.

7-32
 Chapter 7
Organize products in collections

Collections, except root collections, can belong to multiple catalogs. See Link and unlink
collections and products for more information.
To create new products in a collection, see Create products. To link existing products to a
collection, see Link and unlink collections and products.

Understand Unassigned Products and Unassigned Collections

Products and collections that are not assigned to any parent in any catalog hierarchy appear
in these lists above the collection hierarchy on the Catalog page. Products that are not part of
any collection appear in the Unassigned Products list. Collections that have no parent
collection appear in the Unassigned Collections list.
Unassigned products do not appear in the navigation for your store and are not returned in
any search results. Unassigned collections are not returned in search results.
A product or collection becomes unassigned when one of the following things happens:
• It has been removed from all other collections.
• It has been unlinked from all parents.
• It is imported into Commerce with no parent collection.
• You specifically created a product in Unassigned Products.
You can view and work with unassigned products and collections just as you do any others in
your catalog hierarchy. You cannot create new collections or drag existing collections in the
Unassigned Collections lists. You can link a product or collection to a collection in the
Unassigned Collections list. You can create new product in the Unassigned Products list but
you cannot link an existing product there.
There are several ways to move an item out of the Unassigned Products or Unassigned
Collections lists:
• Drag both products and collections to a parent in the catalog hierarchy.
• Move both products and collections to a parent in the catalog hierarchy. See
• Link collections to a parent in the catalog hierarchy. See Link and unlink collections and
products for more information.

Create collections
You can create a collection that is a child of either of the two root collections, Storefront
Navigation or Non-Navigable. You cannot create a new collection at the root level of a
catalog.
This section describes how to create a new collection. To link an existing collection, see Link
and unlink collections and products.
To create a new collection:
1. On the Catalog page, click the New Collection button and select New from the list that
appears.
2. Fill in the property fields in the New Collection screen.
3. Click Save.
The following table describes the properties Commerce provides for collections. You can also
use the REST APIs to create custom properties for collections. See Create custom properties
for collections for more information.

7-33
 Chapter 7
Organize products in collections

Property Description
Name (required) Short, descriptive name that identifies the
collection. Collection names do not have to be
unique.
Collection ID (required) The ID that identifies the collection internally.
Each collection ID must be unique within your
catalog.
Description A short description to display with the
collection.
Long Description Detailed descriptive text to display with the
collection. The long description is created with
an HTML editor called CKEditor that you can
use to edit and apply rich-text formatting.
Exclude from XML Sitemap Excludes selected collections from the
collections sitemap.
The XML sitemap is an index of page URLs on
your site that is available for crawling by
search engines. It helps search engines to
crawl your site more intelligently.
Selected Parents All the collection’s parent collections.
By default, when you create a new collection, it
has a single parent, Storefront Navigation.
To change a collection’s parents, click the Edit
button and select collections from the list. See
Link and unlink collections and products for
more information.
To make the collection a child of another
collection, select a collection in the Change
Parent list.
If you remove all a collection’s parents,
Commerce moves it to the Unassigned
Collections list.
Status Specifies whether the collection is displayed
on your store.
Active: The collection is displayed on your
store.
Inactive: The collection is not displayed on
your store. This is the default setting for new
root collections.
Inherited from parent: The collection’s status is
the same as its parent. This is the default
setting for new child collections.

Reorder products in collections

Each product has a specific position in the collection. The page coding in the
Commerce layouts and widgets uses the position to control the order in which
products appear on the collection pages.
If you reorder products in a collection that is linked to other collections or catalogs, the
collection’s product order is the same in all places the collection appears.
To reorder products in a collection:

7-34
 Chapter 7
Organize products in collections

1. On the Catalog page, navigate to the collection that contains products you want to
rearrange.
2. You can drag a product to a new position in either Grid View or List View.
3. To use numbers to move a product to a new position in the collection, click the List View
button at the top of the page, then change the product's number.
Enter a number from 1 to the number of products in the collection. If the number you
enter is greater than the number of products, rearranging moves the product to the end of
the list.
4. To move a product to the top of a collection, click the arrow icon at the right-hand side of
the product’s tile.

Move collections
You can reorder collections by dragging them to new positions in an independent catalog’s
collections list: If a collection is linked to multiple parents, the new order is the same in all
catalogs. You cannot move a collection to the root position in a catalog. You cannot move a
parent collection to one of its children.
1. On the Catalog page, navigate to the collection you want to move.
2. Perform one of the following tasks:
• Drag the collection to a new position in the hierarchy and drop it. A vertical line
appears at a potential drop location when you hover over it.
• Right-click the collection and click Edit. Click the Edit button next to the Selected
Parents field and select a new parent for the collection.

Find products in collections

To learn how to perform custom, rule-based searches for products in collections and
catalogs, see Find products in catalogs.

Sort products in collections

To display a collection of products, click the corresponding link in the left column of the
Catalog page, and then choose a sort option from the Display Order list. The list includes
options for sorting by name, ID, or price, in ascending or descending order.
Note that the Display Order list is disabled for search results.

Delete collections
Deleting a collection that has more than one parent removes it from all parent collections. You
can delete only empty collections. If you want to delete a collection that contains products or
other collections, remove them first.
To delete a collection:
1. On the Catalog page, navigate to the collection you want to delete.
2. Click the edit link.
3. In the collection’s details dialog, click Delete.
4. Confirm that you want to delete the collection.

7-35
 Chapter 7
Organize products in collections

Remove products from collections

Removing products from a collection does not remove them from the catalog. If a
product has more than one parent collection, removing it from one collection does not
automatically remove it from others. If you remove a product from its only parent
collection, it is automatically moved to the Unassigned Products list.
You can also remove a product from a collection on the product’s details page. See
Link and unlink collections and products for more information.
To remove products from a collection:
1. On the Catalog page, navigate to the collection where you want to remove
products.
2. Hover over the product to remove until the remove icon appears.
Tip: To remove multiple products, select all the products you want to remove and
then click the remove icon on any of them.
3. Click the remove icon.

Add images to collections

Use a collection’s Media tab to upload and arrange collection images that will appear
on your store, for example, a hero image that appears on a category landing page.
You can upload JPG, PNG, and GIF files. Commerce automatically sizes your images
for display on different devices, such as laptops, tablets, and mobile phones.
Note: This section describes how to upload images to individual collections. See
Manage Media for your Store for information about using the media library, including
information about uploading a ZIP file of images and other types of media that are
automatically assigned to products and collections in your catalog.
Once you assign images to a collection, you can tag them to specify how they are
displayed on your store via the Category Content widget. For example, an image
tagged with Hero is displayed as the hero image on the category landing page. For
more information about the Category Content widget, see Design Your Store Layout.
To add an image to a collection:
1. On the Catalog page, navigate to the product to which you want to add images.
2. On the product’s Media tab, click Add Images and select Add New.
3. Select an image to upload.
You can upload only one image at a time. If you select a file with the same name
as a file you already uploaded, the new file replaces the existing one.
4. Click Save.
To assign an image to a product from the media library:
1. On the Catalog page, open the product to which you want to add images.
2. On the product’s Media tab, click Add Images and select Media Library.
3. Select images to assign to the product and click Add.
For details about selecting, sorting, and searching for images in the media library,
see Manage Media for your Store.
4. Click Save.

7-36
 Chapter 7
Configure catalogs with optional collections

To tag an image for display in the Category Content widget:

1. On the Catalog page, open the collection whose images you want to tag.
2. On the collection’s Media tab, hover over the image and click the Tag icon.
3. Click the Tags field and select a tag value to assign to the image.
You can select Hero, Large, Medium, Small, or Thumbnail.
You can assign the same tag to more than one image. For example, if you assign the
Hero tag to several images for the same collection, the images are displayed in a
carousel on the category landing page.
4. Click the check mark icon to save your tags.
5. Click Save.

Configure catalogs with optional collections

You can link products directly to an independent catalog without adding them to any
collections.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

By default, you add products to collections to organize your catalog into a hierarchy and
provides a navigational framework for your store. You can also link products directly to a
catalog, without adding them to any collections. Linking new products directly to a catalog
can speed up catalog deployment, especially for large catalogs.

Understand catalogs with optional collections

You can link products directly to independent catalogs; you cannot link products directly to
legacy catalogs or to a filtered view of an independent catalog. (Catalogs with directly-linked
products do support filtered views, however.)
You can create catalogs with all products directly linked, or you can create catalogs that
include a mix of directly-linked products and products in collections. You can also add
directly-linked products to collections, except in the default Product catalog that ships with
Commerce; product linked directly to that catalog cannot be in any of its collections.
Note: If your environment uses a default collection for products, a product directly linked to
the catalog will also be added to the default collection for products. See Create default parent
collections for more information about setting a default collection for products.
On your storefront, shoppers can find directly-linked products by searching. Keep in mind,
though, that by default, collections control catalog hierarchy and navigation.
Therefore,shoppers cannot browse to products that are only directly-linked to a catalog
unless you have created a custom menu/taxonomy structure with custom links. Storefronts
that are driven entirely by search require this type of customization, for example.

Understand the difference between optional collections and filtered views

A filtered catalog provides a filtered view of an existing independent catalog. Catalogs with
directly-linked products do support filtered views, and while both features can speed up
catalog creation and deployment, they address different merchant concerns.
• Filtered views let merchants scale to a larger number of catalogs with less work and
provide flexibility for merchants who sell to a number of accounts or in a number of
countries. Filtered catalogs provide central management of collections and taxonomies

7-37
 Chapter 7
Configure catalogs with optional collections

and give merchants fine-grained control over the availability of products for each
account or country while maintaining a single collection structure across catalogs.
• Directly linking products to catalogs lets merchants who have very large catalogs
deploy more quickly because they do not have to manage collections and assign
products to them. Directly linking products to catalogs is especially useful for
merchants who want a purely search/facet driven storefront or those who manage
their taxonomies externally and do not want to replicate this effort in Commerce.
• Filtered views and direct linking of products can be used together and can be
especially useful for merchants who need to scale to a larger number of catalogs
but who also manage taxonomies externally.
For more information about creating filtered views, see Work with filtered catalogs.

Find products directly linked to catalogs in the administration interface

You can quickly find products that are linked directly to catalogs by performing a rule-
based search on the Catalog page in the administration interface.
To create the search rule, follow these steps:
1. On the Catalog page, click Search Products and then click the Custom Search
icon next to the search text box.
2. Select a product type to use from the Product Types list, then click the Create
Rule button. You can select only one product type per rule.
3. Select Directly Linked Catalogs from the drop-down list in the rule. You can
select only one property per rule.
4. Select an operator that links the property to a value that you will specify in the next
step. You can select contains, does not contain, exists, or does not exist.
5. If you selected the operator contains or does not contain, select a catalog to
search. If you selected the operator exists or does not exist, you do not need to
select a catalog.
6. Click Search.
For more information about searching for products, see Find products in catalogs.

Link products directly to a catalog

This section describes how to link a product directly to a catalog in the administration
interface. To learn how to link products to a catalog by importing them, see Import
catalog items and inventory. To learn how to link products to a catalog with the REST
API, see information about the /ccadmin/v1/products endpoints using the
directCatalogs parameter in the REST API for Oracle Commerce documentation.

To link an existing product to a catalog:

1. On the Catalog page, navigate to the product you want to link. See Find products
in catalogs for more information.
2. On the product’s Membership tab, click the Edit List button under Directly
Linked Catalogs.
3. Display available catalogs by typing or pasting some text in the search box.
The filter control matches letters or numbers that you type, wherever they appear
in the name or ID, not just at the beginning. Usually, as you type more characters,
there are fewer matches. When you see the item you want, select it.

7-38
 Chapter 7
Link and unlink collections and products

4. Select one or more catalogs and click Add Selected.

5. (Optional) to unlink the product from a catalog, remove a catalog from the Selections list.
• To remove a single catalog, click the x at the end of a catalog's name.
• To remove all catalogs from the list, click the Clear List button.
6. Click Done when you finish adding catalogs.

Import and export products directly linked to catalogs

You can use the Import and Export features on the administration interface Catalog page to
import and export products that are directly linked to catalogs. See Import and Export Catalog
Items and Inventory for details about how to perform bulk import and export of products in
Commerce.
The easiest way to format a file for importing related products for products is to start by
exporting a file that you can use as a template for the items you want to add or modify. See
Export catalog items for more information about how to export products.
When you look at the exported spreadsheet, you can see that the second row displays
column headings that contain the internal names of the exported properties. The
directCatalogs column includes catalog IDs for the catalogs that products are directly linked
to.
Product data begins in the third row and continues for the remainder of the spreadsheet. If an
item does not have a value for a property, the corresponding cell is blank. If the first row of
the spreadsheet includes a catalog context in the sixth column (F1), for example,
CATALOG=movieCat, the directCatalogs column can contain only the catalog ID specified in
the in the header, otherwise, the data will not import successfully. If the spreadsheet does not
include a catalog context, the directCatalogs column can contain any valid catalog ID from
your Commerce instance. To directly assign a product to multiple catalogs, separate each ID
with a comma.
See Import catalog items and inventory for more information about how to import your
changes back into the catalog.

Link and unlink collections and products

Linking a collection or product associates it with a parent.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Linking is useful when you want a product to appear in multiple collections or a collection to
appear in multiple catalogs. Linked items have multiple parents, one parent for each location.
When you make a change to the item in one location, that change is reflected in all locations.
For example, suppose your catalog contains a product called Gas Hibachi in the Outdoors
collection and you want it to also appear in a seasonal Father’s Day Gifts collection. You can
simply link it to that collection.
You can link both products and collections to multiple parent collections. To link a collection to
another catalog, add it to the catalog’s Included Collections list. (See Understand catalogs for
more information.)
This section includes the following topics:
• Link and unlink products

7-39
 Chapter 7
Link and unlink collections and products

• Link and unlink collections

Link and unlink products

You can link a product to one or more collections. Products appear in more than one
catalog when they are linked to collections that are part of different catalogs.
If you unlink a product from all its parent collections, Commerce moves it to the
Unassigned Products list.
To access all products in your environment, regardless of their parent collections or
catalogs, click the All Products lists that appears above the collection hierarchy on the
administration interface Catalog page. See Find products in collections for more
information.
To link an existing product to a collection:
1. On the Catalog page, navigate to the collection where you want to link products.
2. Click the New Product button and select Link Existing Products from the menu
that appears.
3. By default, Commerce lets you search for products in all catalogs. To search for
products in a specific catalog, click the Catalogs button and select a catalog.
4. Select one or more products from the list. You can filter the list by typing or pasting
some text in the Products box.
The filter control matches letters or numbers that you type, wherever they appear
in the name or ID, not just at the beginning. Usually, as you type more characters,
there are fewer matches. When you see the item you want, select it.
5. Click Add Selected.
6. Click Done when you finish adding products.
To link products to multiple parent collections at the same time
1. On the Catalog page, navigate to the product you want to work with and open it.
2. On the product’s Membership tab, click the Edit button.
3. By default, Commerce lets you search for collections in all catalogs. To search for
products in a specific catalog, click the Catalogs button and select a catalog.
4. Select a collection from the list. You can filter the list by typing or pasting some text
in the Collections box.
The filter control matches letters or numbers that you type, wherever they appear
in the name or ID, not just at the beginning. Usually, as you type more characters,
there are fewer matches. When you see the item you want, select it.
5. Click Add Selected.
6. (Optional) to unlink the product from a collection, remove a collection from the
Included Collections list.
• To remove a single collection, click the x at the end of a collection’s name.
• To remove all collections from the list, click the Remove All button.
7. Click Done when you finish adding collections.

7-40
 Chapter 7
Create default parent collections

Link and unlink collections

You can link a collection to one or more parent collections. If you unlink a collection from all
its parent collections, Commerce moves it to the Unassigned Collections list. See Work with
independent catalogs to learn how to link collections to catalogs.
To link a collection to a parent:
1. On the Catalog page, navigate to the collection you want to be the parent.
2. Right-click the collection in the tree and click Link Existing Collection.
3. By default, Commerce lets you search for collections in all catalogs. To search for
products in a specific catalog, click the Catalogs button and select a catalog.
4. Select a collection from the list. You can filter the list by typing or pasting some text in the
Products or Collections box.
The filter control matches letters or numbers that you type, wherever they appear in the
name or ID, not just at the beginning. Usually, as you type more characters, there are
fewer matches. When you see the item you want, select it.
5. (Optional) By default, the collection you right-clicked is automatically selected as the
parent collection, but you can change it by selecting a new collection from the Select
Parent Collection list.
6. Click Link.
To unlink a collection from a parent:
1. On the Catalog page, navigate to the collection you want to unlink.
2. Right-click the collection in the tree and click Unlink From Parent.
If you unlink a collection from its last parent, Commerce moves it to the Unassigned
Collections list.

Create default parent collections

A collection or product can be the child of more than one collection, in more than one catalog.
Its default parent is the collection that determines its hierarchy in a catalog.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Linking products and collections to multiple catalogs provides a more flexible catalog strategy,
but can complicate navigation. This is especially true if a shopper accesses a collection or
product through a search engine rather than by traversing the catalog hierarchy.
A product or collection's parentCategory and parentCategoryScope properties allow you to
specify a default parent collection for each catalog where a product or collection is linked.
The value of parentCategory must be the categoryId of a collection that is one of the item's
existing parents.
The scope of the parent setting, that is, where it should be applied, is specified by its
parentCategoryScope property. You set both properties when you create or update a
collection with the createCollection and updateCollection endpoints, or when you create
or update a product with the createProduct and updateProduct endpoints.

The parentCategoryScope property can have one of the following values:

7-41
 Chapter 7
Create default parent collections

• base specifies that the parentCategory collection is the default parent in all
catalogs where it is included. Use this scope when you want to specify the default
parent collection that should apply wherever the collection or product is shared,
unless it is overridden for a specific catalog.
• catalogSpecific specifies that the parentCategory collection is the default parent
only for the catalog specified by catalogId. Use this scope for a product that
should be available only in a specific catalog, for example, a product that can be
sold only in a certain country. Setting a catalogSpecific value does not change
the existing base value. If no base value is set, Commerce automatically sets the
base value as the same value you set for catalogSpecific.
• global specifies the default parent category for a product or collection and applies
it in every catalog where the item appears. The global scope resets the base
scope value and removes all catalog context from the collection or product's
default parent.
• revertToBase removes the catalogSpecifc scope for the catalog in context for
the product or collection and sets its default parent back to the base scope.
If no scope is specified in a PUT or POST request, and a catalog-specific value exists,
the request uses that value. Otherwise, the request uses the base value.

Set a default parent for a collection

This section contains Admin API examples that show how to set a default parent for a
collection. To update a collection, issue a PUT request to the /ccadmin/v1/
collections/{id} endpoint. To create a collection, issue a POST request to the /
ccadmin/v1/collections/{id} endpoint.

The examples in this section are based on the following scenario:

A Commerce instance includes two sites, one for US shoppers and one for UK
shoppers. Each site has its own catalog, usCatalog and ukCatalog, respectively. The
BigBrand collection is linked to the following locations in both catalogs:
• UK-Catalog / StorefrontNav / New / BigBrand
• UK-Catalog / StorefrontNav / Brands / BigBrand
• US-Catalog / StorefrontNav / New / BigBrand
• US-Catalog / StorefrontNav / Tableware / Brands / BigBrand
The following example updates the default parent collection for BigBrand to Brands.
This change affects both catalogs, since the Brands collection exists in both.

PUT /ccadmin/v1/collections/bigBrand

{
"properties":{
"parentCategoryScope": "base",
"parentCategory" : "Brands"
}
}

7-42
 Chapter 7
Create default parent collections

The following example updates the default parent collection for BigBrand to New in the US
Catalog only. It does not affect BigBrand's default parent collection in the UK Catalog.

PUT /ccadmin/v1/collections/bigBrand

{
"properties":{
"catalogId": "usCatalog",
"parentCategoryScope": "catalogSpecific",
"parentCategory" : "New"
}
}

The following example updates the default parent collection for BigBrand to Brands. This
change affects both the US and UK catalogs, even if a catalog-specific default parent was
previously set, as in the previous example.

PUT /ccadmin/v1/collections/bigBrand

{
"properties":{
"parentCategoryScope": "global",
"parentCategory" : "Brands"
}
}

The following example updates the default parent collection for BigBrand to New in the UK
Catalog only. It does not affect BigBrand's default parent collection in the US Catalog.

PUT /ccadmin/v1/collections/bigBrand

{
"properties":{
"catalogId": "ukCatalog",
"parentCategoryScope": "catalogSpecific",
"parentCategory" : "New"
}
}

The following example clears the catalog-specific parent setting from the previous example.
The default parent collection for BigBrand in the UK Catalog is now set to Brands, which was
set as the base value in the first example in this section. Note that the request includes a
catalog context ("catalogId": "ukCatalog"). A catalog context is required to set the
parentCategoryBase torevertToBase.

PUT /ccadmin/v1/collections/bigBrand

{
"properties":{
"catalogId": "ukCatalog",
"parentCategoryScope": "revertToBase"

7-43
 Chapter 7
Create custom properties for collections

}
}

Set a default parent for a product

This section contains Admin API examples that show how to set a default parent for a
product with the /ccadmin/v1/products endpoints. To update a product, issue a PUT
request to the /ccadmin/v1/products/{id} endpoint. To create a product, issue a
POST request to the /ccadmin/v1/products/{id} endpoint.

The code examples in this section are based on the following scenario:
A Commerce instance includes two sites, one for US shoppers and one for UK
shoppers. Each site has its own catalog, usCatalog and ukCatalog, respectively. A
serving platter is linked to the following locations in both catalogs:
• UK-Catalog / StorefrontNav / New / Large Oval Platter
• UK-Catalog / StorefrontNav / Brands / BigBrand / Large Oval Platter
• US-Catalog / StorefrontNav / New / Large Oval Platter
• US-Catalog / StorefrontNav / Tableware / Large Oval Platter
The following example updates the default parent collection for the Large Oval Platter
to New. This change affects both catalogs, since the New collection exists in both.

PUT /ccadmin/v1/products/prod_largeOvalPlatter

{
"properties":{
"parentCategoryScope": "base",
"parentCategory" : "New"
}
}

Create custom properties for collections

Collections include a predefined set of properties that store information about
collections you use to organize your catalog.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

In addition to these predefined properties, you can create custom collection properties.
This section describes how to use the Commerce Admin REST APIs to add custom
properties to collections. See Use the REST APIs for information you need to know
before using the APIs.

Understand item types

Item types are templates for Commerce assets, such as collections and promotions.
They contain properties that describe the asset.
The category item type lets you work with the collections in a Commerce catalog. You
can use the updateItemType endpoint to modify the category item type. You can
modify existing properties by changing the values of their attributes and create custom

7-44
 Chapter 7
Create custom properties for collections

properties by specifying their attributes. SeeSettable attributes of shopper type properties for
descriptions of these attributes. The next section provides an example of creating a custom
property for collections.

Create a custom collections property

To add custom properties to the category item type, issue a PUT request to the /
ccadmin/v1/itemTypes/category endpoint on the administration server.

Use the following format:

• The request header must specify the x-ccasset-language value.
• The request body is a map where each key is the ID of a new property, and each value is
an object that specifies the values of the attributes of the property.
• Each object is also a map, with each key being the name of an attribute and each value
being the corresponding attribute value.
Note that the ID of a custom property must include the underscore character (_). This
ensures that the ID will not conflict with any properties that Commerce adds to item types in
the future. The endpoint returns an error if you attempt to create a custom property without an
underscore in its ID.
Remember to publish the new property once it is successfully created. See Publish Changes
for more information.
The following example shows a sample request for adding a custom text property to the
category item type:

PUT /ccadmin/v1/itemTypes/category HTTP/1.1

Authorization: Bearer <access_token>
x-ccasset-language: en
Content-Type: application/json

{
"specifications": [
{
"id": "_myNewProperty",
"label": "My New Property",
"type": "shortText",
"required": false,
"uiEditorType": "shortText",
"uiwritable": "true",
"localizable": false,
"hidden": false,
"propertySortPriority": "100"
}
]}

The response includes the property you created.

...
{
"hidden": false,
"length": 254,
"label": "My New Property",

7-45
 Chapter 7
Create custom properties for collections

"type": "shortText",
"required": false,
"searchable": false,
"writable": true,
"internalOnly": false,
"uiEditorType": "shortText",
"default": null,
"audienceVisibility": null,
"localizable": false,
"textSearchable": false,
"id": "_myNewProperty",
"dimension": false,
"propertySortPriority": "100",
"editableAttributes": [
"internalOnly",
"default",
"audienceVisibility",
"hidden",
"textSearchable",
"label",
"dimension",
"propertySortPriority",
"required",
"searchable"
]
}
...

When you add a custom property to the category item type, the property is added to all
collections, including any new collections you create and any collections that already
exist. It appears on the General tab of every collection's details page in the
administration interface. Business users can view, add, and edit values for custom
collection properties, just as they do for predefined properties. (See Organize products
in collections for more information.) Custom collection properties themselves cannot
be edited in the administration interface; you can perform these tasks only with the
Admin API.

Access custom collections properties

Storefront and Agent Console developers can access custom properties of the
category item type with the following Store API and Agent API endpoints:

• getCollection returns a collection by ID.

• listCollections returns a list of collections by a list of IDs.
• listItemTypes returns information about item types by a list of IDs.
• getItemType returns information about an item type by ID.
• getPage returns a specific page. For category page responses, custom properties
are also returned as part of the response.
Keep the following points in mind when accessing custom properties with Store or
Agent endpoints:

7-46
 Chapter 7
Add metadata to products and collections

• If a custom property is specified as internal only (by setting the attribute

internalOnly=true when you create the property), it will not be returned by any Store
endpoints.
• Custom properties appear at the top level of the response.
• Only getCollection returns custom properties for child collections. The request must
include the parameter expand=childCategories. For example:

GET /ccstore/v1/collections/rootCategory?
catalogId=storefrontCatalog&maxLevel=1000&expand=childCategories&fields=ch
ildCategories%28items%29

• There is no view model support for custom properties of the category item type.

Add metadata to products and collections

You can enter metadata search information including a title, keywords, and a description for
each product and collection in your catalog.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The metadata is then tagged and retrieved as part of a search via a search engine and
displayed in the results.
This section describes how to add metadata to products and collections. You can also add
alt-text and titles to images assigned to products and collections. See Add alt text and titles to
images for more information.
To enter metadata for a product or collection:
1. On the Catalog page, open the relevant product or collection for which you want to enter
metadata search information.
2. Open the product or collection’s Metadata tab. By default, the following properties are
automatically assigned to metadata when a product or collection is created:
• Title Tag: The Name of the product or collection.
• Meta Keywords: The Name and Parent Collection of a product. The Name and
Selected Parent of a collection.
• URL Slug: The Name of the product or collection.
• Meta Description: The Name and Description of the product or collection.
3. To change the current information you must check Edit Manually and enter the text
within each box.
To change back to the default alt text, check Edit Manually and click Reset Default.
4. Enter a Title Tag. This is normally the product or collection title.
5. Enter Meta Keywords. These are used by search engines to find the most relevant
information when processing a search request. Search engines determine the relevance
of a search request against these keywords.
6. Enter a URL Slug. This is a unique, URL-friendly version of the Name of the product or
collection. A URL slug can contain only lowercase letters (a-z), numbers (1-9), and a
limited number of special characters (- _ % ~). Using a unique URL slug ensures that you

7-47
 Chapter 7
Display related products

do not encounter storefront display issues, such as, 404 errors. See Configure
URL patterns for more information
For example, for the product named Button Down Shirt, the URL slug could be
button_down_shirt.
See Understand canonical tags for information on signaling the source, or original,
URL of a page to search engines.
7. Enter Meta Description. This description can promote your site to search engine
users.
8. Click Save.

Display related products

Use a product’s Related Products tab to select products to display in the Related
Products widget on the Product layout and specify the order in which the related
products appear.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Use the Details tab to configure how the products look in the widget, for example,
whether names and prices are displayed for related products. For more information,
see Design Your Store Layout.
This section includes the following topics:
• Add and organize related products
• Import and export related products

Add and organize related products

To select and organize related products:
1. On the Catalog page, navigate to the product to which you want to add related
products.
2. On the product’s Related Products tab, click Manage Products.
3. Select products to display.
To select products, begin by typing or pasting some text in the box. The list of
products that appears matches letters or numbers that you type, wherever they
appear in the asset name or ID, not just at the beginning.
Note: If you select inactive products, the Related Products widget will not display
them. For more information about active and inactive products, see Understand
the base product type.
4. When you finish adding related products, click Display Products.
The Related Products widget will display the products in the order they appear
here. You can rearrange them by dragging them to new positions.
5. Click Save.

Import and export related products

You can use the Oracle Commerce import process to import and export a product’s
fixed related products. See Import and Export Catalog Items and Inventory for details
about how to import and export products in Oracle Commerce.

7-48
 Chapter 7
Configure AI Recommendations Rules

The easiest way to format a file for importing related products for products is to start by
exporting a file that you can use as a template for the items you want to add or modify. See
Export catalog items for more information about how to export.
When you look at the exported spreadsheet, you can see that the second row displays
column headings that contain the internal names of the exported properties. The
fixedRelatedProducts column includes product IDs for the products to display in the Related
Products widget on the Product layout.
Product data begins in the third row and continues for the remainder of the spreadsheet. If an
item does not have a value for a property, the corresponding cell is blank. When you import
multiple related products, separate each ID with a comma. The order of the IDs in the
spreadsheet controls the order of products displayed on the product details page.
See Import catalog items and inventory for more information about how to import your
changes back into the catalog.

Configure AI Recommendations Rules

Commerce lets you create complex recommendation strategies in the administration
interface. You can manage these rules across widgets on different page layouts.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Product recommendations are generated by an AI-powered learning engine. Strategies and

global exclusions work in harmony with this engine to provide granular control over the
merchandising experience.
• Recommendation strategies are rules you build to customize the kinds of products that
are recommended to shoppers.
• Global exclusions are rules you build to prevent certain products from ever being
recommended to shoppers.

Understand recommendations strategies

Commerce product recommendations are generated by an AI-powered learning engine. The
engine analyzes each shopper's behavior in real time to recommend the most relevant
products at every interaction.
Commerce provides a number of pre-defined strategies that let you restrict displayed
recommendations, for example, to products the shopper has most recently viewed, or
products that are most frequently bought by other shoppers who have also viewed a product
that a shopper is currently viewing.
In addition to these pre-built strategies, Commerce lets you create your own strategies that
provide customized guidance to the recommendations engine. You can use strategies to
restrict the kinds of products that are recommended, creating a more curated experience for
shoppers and providing the flexibility to tailor your recommendations plan to match your
merchandising goals.
Each custom strategy is made up of one or more recommendation groups. A
recommendation group is a set of conditions that are evaluated together to specify a group of
product recommendations. If a strategy includes multiple recommendation groups, the
Product Recommendations widget will display products returned by each recommendation
group sequentially, that is, all products returned by the first recommendation group, followed
by all products returned by the second recommendation group, and so on.

7-49
 Chapter 7
Configure AI Recommendations Rules

If a product is returned by multiple recommendation groups in a strategy, it appears

only once in the Product Recommendations widget. The product’s display position will
be determined by the first recommendation group that returns it.
The following table describes each type of condition you can add to a recommendation
group.

Condition type Description

Brand The value of the product’s brand property in
the context of the current product or products
being viewed. If there are multiple products,
such as the products in a cart or a wish list,
products in any of the brands can be part of
the condition.
Browsed Together Returns recommended products based on the
most frequently browsed products by other
shoppers associated with the product the
shopper is currently viewing.
Collection The condition returns products based on either
the same collection or collections in the
context of the current product or products
being viewed, or only in collections you
specify. If multiple collections are represented,
products in any of the collections can be
recommended. If there are no collections in
context, no restrictions are placed on the
recommendations.
A product can be in one or more collections.
For more information, see Organize products
in collections.
Manually Related Products Returns recommended products based on the
products specified as related products for the
current product or products being viewed. See
Display related products for more information
about adding related products to a specific
product.
Most Recently Viewed Returns products the shopper has viewed.
Recommended products are displayed starting
from the most recently viewed. First-time
shoppers on the site are offered no product
recommendations.
Price Lets you select a price range of products to
recommend.
Price Type Lets you select products from specific price list
groups to recommend.
Purchased Together Uses the context of the product the shopper is
currently viewing. Recommended products are
displayed based on the most frequently
purchased products by other shoppers
associated with the product the shopper is
currently viewing.

7-50
 Chapter 7
Configure AI Recommendations Rules

Condition type Description

Top Sellers Restricts recommendations to global top
sellers. If the recommendation group contains
other conditions, Top Sellers will be applied
after all other rules.
The algorithm for the Top Sellers strategy is
based on products purchased. It generally
considers the top ten percent of recently-
purchased products from the product catalog
to offer as recommendations. The strategy
does not offer products in a sequential order of
most purchased items and has no time
restrictions as to when items were purchased.
Top Sellers is designed to personalize items
recommended to each unique shopper. While
a particular product might sell more frequently
than other products, that product may not be
recommended based on a shopper’s
navigation of the site.

Understand product context

Product context lets you decide whether a condition for a recommendation group or exclusion
rule should be dynamically inferred from the current page. The following procedure explains
the steps Commerce goes through to provide context for recommendations conditions when
the shopper is viewing pages on your store:
1. If the current page has a brand or collection, it is used for the context of Brand or
Collection.
2. Otherwise, if the current page has a product, its brand, parent collections, co-browses,
and co-buys are used as the context for Brand, Collections, Browsed Together, and
Purchased Together conditions.
3. Otherwise, if there are current wish lists, the products in the wish lists are used to define
the context as described in the previous step.
4. Otherwise, if an order has been placed in the current session, the products in the order
are used to define the context as described in step 2. An order is defined as an item that
has been purchased during the shopper’s current session. The item could have been
placed in the cart during a past session.
5. Otherwise, if the shopper has added products to their cart but not purchased them (either
in this session or their most recent previous session), the products in the cart are used to
define the context as described in step 2.
6. Otherwise, no context is found, so the current condition will not apply.

Understand recommendations for account-based shoppers

Commerce lets you create accounts for companies that do business with you, such as
manufacturers, distributors, and wholesalers. Each account represents a single organization
and a unique customer. Shoppers who are associated with an account are called contacts.
The recommendations engine considers the behavior of all contacts who are members of an
account when determining which recommendations to show an individual contact. (This also
applies to recommendations strategies and exclusions you create.) While recommendations
continue to be generated for an individual contact, Commerce also factors in key information

7-51
 Chapter 7
Configure AI Recommendations Rules

about other contacts within the same account. Shared account behavior ensures that
buyers now see relevant recommendations based on interaction from all buyers
across an account.
For example, suppose buyers within the same account are viewing and purchasing the
same products. To enhance the quality of recommendations, the Commerce
aggregates information about related purchases and customer behavior to optimize
the quality and breadth of products that are recommended.
For more information about working with account-based stores and shoppers, see
Configure Business Accounts.

Display recommendations
Once you have created and published custom recommendations strategies, you can
customize the Product Recommendations Carousel widget to use specific strategies
for different locations on your site. This helps you create more specialized product
selections appropriate to each shopper's current context. When you customize the
widgets settings on the Design page in the administration interface, you can select any
custom strategies you published, along with the out-of-the-box strategies. For more
information, see Display product recommendations.

Create recommendation strategies

To create a recommendation strategy, follow these steps:
1. On the Marketing page, click Strategies under AI Recommendations.
2. Click the New Strategy button.
3. Enter the name, ID, and optional description for the strategy.
Strategy Display Name: A name for the strategy that will appear in the list of
strategies in the administration interface. Each global strategy name must be
unique. The name can be up to 50 characters long.
Strategy ID: Commerce automatically creates a unique ID based on the display
name you entered. You can change the ID while you are creating the strategy, but
you cannot change it once the strategy is saved. An ID can contain only
alphanumeric characters or numbers (a-z, A-Z, 0-9) and must be unique.
Strategy Description: An optional description of the strategy that helps other users
understand it. The description can be up to 1,000 characters long.
4. Define the strategy by adding recommendation groups. By default, a blank
recommendation group is already visible and ready for you to add conditions.
5. Click the Add Condition button.
6. Select a value from the Select a condition type list. You can select only one type
per condition. For details about each condition type, see the table earlier in this
section.
7. If you selected Brand, Collection, Price, or Price Type, you must select an operator
that links the property to a value that you will specify in the next step. The
operators you see depend on the condition type you selected.
• For Brand and Collection, you can select is, which matches the rule to the
property you will select in the next step or is same as context, which matches
the rule to .

7-52
 Chapter 7
Configure AI Recommendations Rules

• For Price you can select from several numeric operators that match the rule to prices
or price ranges. For example, select is less than if you want the condition to return
all products priced at less than $50.
• For Price Type you can select is, which matches the rule to a single price group, is
one of, which matches the rule to more than one price group, or is same as context,
which matches the rule to the shopper’s current price group.
8. Select or enter a value for the condition property. For Collection and Price Type,
Commerce displays a list for you to choose from. For Brand and Price, you must type in a
value. The rule editor does not validate any text, numeric, or date values you type.
9. To add another condition to the recommendation group, click the Add Condition button
again and specify the details for the new condition.
If a recommendation group contains more than one condition, it returns products that
match all the conditions. Products that match only some of the conditions but not all, are
not returned by the recommendation group.
10. When you are finished adding conditions to the recommendation group, click Save.

11. To add another recommendation group to the strategy, click Add Recommendation
Group.
12. When you are done adding recommendation groups, click Save to save the strategy.

13. You must publish strategies in order for them to take effect on your production storefront,
though once saved, they are immediately available for preview. See Publish Changes for
more information.

Recommendation strategies examples

You could use the AI Recommendations rule builder to create the following sample
recommendations strategies.
• Suppose you want to create a dynamic cross-sell on the Product Detail Page that
focuses on brand affinity. You could create a strategy with the following three
recommendations groups. Set the maximum number of returned products in each group
to four.
– Group 1 includes two conditions: Brand is the same as context and Collection is not
same as context.
– Group 2 includes two conditions: Brand is the same as context and Purchased
Together.
– Group 3 includes two conditions: Brand is the same as context and Browsed
Together.
This strategy recommends up to four products that have the same brand but belong to a
different collection, followed by up to four products that are the same brand and
frequently purchased together, followed by the remaining products that are browsed
together (but not necessarily purchased together).
• Suppose you want to recommend an outfit when the shopper is viewing any apparel item.
A custom recommendations strategy can dynamically generate an outfit recommendation
that automatically promotes products from complementary collections. You could create a
strategy with the following four recommendations groups. Set the maximum number of
returned products in each group to one.
– Group 1 includes two conditions: Collection is Men’s Tops and Collection is not same
as context.

7-53
 Chapter 7
Configure AI Recommendations Rules

– Group 2 includes two conditions: Collection is Men's Pants and Collection is

not same as context, Number of Products = 1.
– Group 3 includes two conditions: Collection is Men’s Shoes and Collection is
not same as context.
– Group 4 includes two conditions: Collection is Men’s Belts and Collection is
not same as context.
To display these recommendations, create a custom Product Details layout where
you define the Product Type as Men’s Apparel and Men’s Footwear and place the
Recommendations widget on the layout. Customize the widget to use this custom
strategy by selecting it from the Strategy dropdown on the widget’s settings.
Now, when the shopper is on any men’s apparel or footwear product details page,
they will see recommendations from the complementary collections.

Create global exclusions

Global exclusion rules let you exclude certain products from all recommendations
results, ensuring they are never recommended to shoppers. You can exclude products
from recommendations based on their brand, parent collections, price range, or price
type. Once you publish a global exclusion, it automatically takes affect on your site.
To select products to exclude from recommendations follow these steps:
1. On the Marketing page, click Global Exclusions under AI Recommendations.
2. Click the New Global Exclusion button.
3. Enter the name, ID, and optional description for the rule.
Global Exclusion Display Name: A name for the rule that will appear in the list of
global exclusions in the administration interface. Each global exclusion rule name
must be unique. The name can be up to 50 characters long.
Global Exclusion ID: Commerce automatically creates a unique ID for the rule
based on the display name you entered. You can change the ID while you are
creating the rule, but you cannot change it once the rule is saved. An ID can
contain only alphanumeric characters or numbers (a-z, A-Z, 0-9) and must be
unique.
Global Exclusion Description: An optional description of the rule that helps other
users understand it. The description can be up to 1,000 characters long.
4. Define the exclusion rule.
Select a type of property to use from the Select a condition type list. You can
select only one type per rule:
• Brand lets you select from all the manufacturer values assigned to products in
your catalog. For more information about the Brand property, see Create and
edit product types.
• Collection lets you select a collection whose products you want to exclude.
You can select a collection from across all catalogs or from a specific catalog.
• Price lets you select a price range of products to exclude.
• Price Type lets you exclude products from specific price list groups.
Select an operator that links the property to a value that you will specify in the next
step. The operators you see depend on the condition type you selected.
• For Brand and Collection, you can select is, which matches the rule to the
property you will select in the next step or is same as context, which matches

7-54
 Chapter 7
Work with the Recommendations API

the rule to whatever product the shopper is currently viewing, as well as any products
in the shopper’s cart or wish lists.
• For Price you can select from several numeric operators that match the rule to prices
or price ranges. For example, select is less than if you want to exclude all products
priced at less than $50 from recommendations.
• For Price Type you can select is, which matches the rule to a single price group, is
one of, which matches the rule to more than one price group, or is same as context,
which matches the rule to the shopper’s current price group.
5. Select or enter a value for the condition property. For Collection and Price Type,
Commerce displays a list for you to choose from. For Brand and Price, you must type in a
value. The rule editor does not validate any text, numeric, or date values you type.
6. Click the Create button when you are finished with rule.
7. You must publish strategies in order for them to take effect on your production storefront,
though once saved, they are immediately available for preview. See Publish Changes for
more information.

Global exclusion examples

You could use the AI Recommendations rule builder to create the following global exclusions.
• Never recommend anything from the brand MySample.
In the Global Exclusion Definition, select Brand as the condition, select is as the
operator, then MySample in the text box.
• Never recommend anything in the Health and Wellness collection.
In the Global Exclusion Definition, select Collection as the condition, select is as the
operator, and then select Health and Wellness (including catalog context) from the
Collection dropdown list.
• Never recommend products that cost less than $25.
In the Global Exclusion Definition, select Price as the condition, select less than as the
operator, and then enter 25 in the text box.
• Never recommend products that are on sale.
In the Global Exclusion Definition, select Price Type as the condition, select is as the
operator, and then select Sale Price from the dropdown list.

Work with the Recommendations API

Use the Recommendations REST API to update visitor tracking state and optionally request
recommendations.
The Oracle Commerce Recommendations service provides personalized product
recommendations to shoppers based on behavior on Commerce storefronts. Product
recommendations are generated by an AI-powered learning engine trained for a wide variety
of ecommerce models with a proven record of increased conversion rate and average order
value.
The Recommendations API lets storefront applications feed shopper behavioral information
to the engine, and to get back personalized product recommendations which the application
can then display to the shopper.
The API exposes a single endpoint, whose payload can perform multiple operations
simultaneously. This allows the engine to reduce the number of HTTP transactions between

7-55
 Chapter 7
Work with the Recommendations API

the application and the service, which optimizes latency, providing a better experience
for shoppers.
The host of the Recommendations endpoint can be retrieved from the Commerce
Store API getExternalServiceData endpoint, using the production-Recommendations
resource. The response will include a protocol, host, port, and path to the
Recommendations API.
For example, suppose you issue the following request:
GET /ccstore/v1/merchant/production-Recommendations

Commerce returns the a response similar to this sample:

{
"serverType": "production",
"serviceData": {
"protocol": "https",
"host": "[Link]",
"port": 443,
"path": "pr",
"displayName": "Oracle Recommendations",
"name":"Recommendations",
"tenantId":"l01234567c1PRD"
},
"links": [{
"rel":"self",
"href":"[Link]
Recommendations"
}],
"id":"production-Recommendations"
}

The serviceData object in the response contains the information necessary to

construct the URL to the Recommendations API endpoint. This information will rarely
change for a given tenant, but it may change on occasion if required by the backing
infrastructure. Therefore, it is best to issue a request to the getExternalServiceData
endpoint at the start of each user session . Once the Recommendations URL has
been constructed, requests to the Recommendations service can be made to the
Recommendations endpoint.

POST /pr/v4/sessions/click

The request body is a JSON payload that contains some top level properties for the
overall request, and a series of operational properties that update the shopper’s state
and request recommendations for the shopper. For details about these properties, see
the Commerce REST API documentation that is available in the Oracle Help Center.
In the following sample request, the shopper visits the store’s home page and then
clicks a product link. The storefront application should issue two requests to the
Recommendations service, one for each page view (the home page and the product
details page.)

7-56
 Chapter 7
Work with the Recommendations API

When the shopper lands on the home page, the client should issue the following request:

POST /pr/v4/sessions/click
{
"tenantId": "p01234567c1PRD",
"catalogId": "mysiteCatalog",
"view": {
"url": "[Link]
"pageTitle": "Mysite Home Page",
"referrer": "[Link]
}
}

The Recommendations service records that information, and returns a response like the
following:

200 OK
{
"token": "aaabbbcccddd"
}

The token in the response contains state information useful to the Recommendations service,
and should be provided in the subsequent request. All POST /pr/v4/sessions/click requests
will include the token property in the response. The value of the token property is not
guaranteed to be the same from request to request. The application must always provide the
token from the most recent response. In addition, the token should be persisted between
shopper sessions, if possible . This helps maintain recommendations continuity for a shopper
across sessions.
Continuing with the previous example, when the shopper clicks the product link on the home
page, the application should inform the Recommendations service using the following
request:

POST /pr/v4/sessions/click
{
"tenantId": "p01234567c1PRD", "token": "aaabbbcccddd", "catalogId":
"mysiteCatalog", "view": {
"url": "[Link] "pageTitle": "Mysite:
Red Shirt",
"referrer": "[Link] "productId": "p02113
}
}

Notice the additional property productId in the request. This tells the recommender that the
shopper is looking at a product on its details page. This is useful information, and is
considered by the Recommendations service the next time the application requests
recommendations for this shopper. The recommendations service sends the following
response. (In this example, it’s the same value as returned in the previous sample response,
but it may change occasionally.)
Commerce lets you create complex recommendation strategies in the administration
interface. Suppose you created recommendation strategies that specified recommendations

7-57
 Chapter 7
Work with the Recommendations API

appear on the product detail page. This request can be modified to ask the
recommender for recommendations. The modified request would look like this:

POST /pr/v4/sessions/click
{
"tenantId": "p01234567c1PRD",
"token": "aaabbbcccddd", "catalogId": "mysiteCatalog", "view": {
"url": "[Link] "pageTitle":
"Mysite: Red Shirt",
"referrer": "[Link] "productId": "p02113"
},
"recommendations": { "pdpRecs": {
"numRecs": 6,
"strategy": "inCollection"
}
}
}

That recommendations section will let the service know that you want some product
recommendations in the response. With the latest data, the service will generate
personalized recommendations for the shopper, with a response like the following:

200 OK
{
"token": "aaabbbcccddd", "recommendations": {
"pdpRecs": {
"recSetId": "342bf3789:32-5",
"recs": [
{ "productId": "p34909" },
{ "productId": "p28200" },
{ "productId": "p11879" },
{ "productId": "p00032" },
{ "productId": "p00877" },
{ "productId": "p21006" }
]
}
}
}

Detailed information about those products (like the localized display name, product
images, and prices for this shopper) can be obtained with API requests to the
Commerce Storefront server. You may also choose to have your application cache this
information locally.
Multiple recommendation sets can be requested in a single HTTP transaction. For
example, if your application has an additional space on the page for recommendations
and you want to use a different strategy, an example request payload might look like
this:

POST /pr/v4/sessions/click
{
"tenantId": "p01234567c1PRD", "token": "aaabbbcccddd", "catalogId":
"mysiteCatalog", "view": {
"url": "[Link] "pageTitle":

7-58
 Chapter 7
Work with the Recommendations API

"Mysite: Red Shirt",

"referrer": "[Link] "productId": "p02113"
},
"recommendations": { "pdpRecs": {
"numRecs": 6,
"strategy": "inCollection"
},
"top": {
"numRecs": 4, "strategy": "topSellers"
}
}
}

The Recommendations service will not recommend the same products in multiple
recommendations sets in the same request. This prevents the application from showing the
shopper the same product in multiple places on a page.
If a shopper clicks a recommended product, the engine would like to know about it. This is an
important piece of feedback, and lets the engine know that the shopper showed interest in a
recommended product. Suppose the shopper clicked on the product whose ID is p11879 from
the request. The application will show the product details for that product, and should issue a
request to the Recommendations service. (The response to this request includes an
additional set of recommendations.)

POST /pr/v4/sessions/click
{
"tenantId": "p01234567c1PRD", "token": "aaabbbcccddd", "catalogId":
"mysiteCatalog", "view": {
"url": "[Link] "referrer":
"[Link] "pageTitle": "Mysite: Comfy
Sandals",
"productId": "p11879"
},
"click": {
"recSetId": "342bf3789:32-5",
"productId": "p11879"
},
"recommendations": {
...
}

Your application should notify the Recommendations service if the contents of the shopper’s
cart changes, for example, when they add or remove an item. The current cart contents are
taken into account when personalized recommendations are made, so it is best to keep the
service up to date with a request like the following sample:

POST /pr/v4/sessions/click
{
"tenantId": "p01234567c1PRD", "token": "aaabbbcccddd", "catalogId":
"mysiteCatalog", "view": {
"url": "[Link] "referrer":
"[Link] "pageTitle": "Mysite: Comfy

7-59
 Chapter 7
Work with the Recommendations API

Sandals",
"productId": "p11879"
},
"cart": {
"productIds": [ "p11879" ], "totalPrice": 48.99, "pricelistGroupId":
"sunnysideStore", "currencyCode": "USD"
},
"recommendations": {
...
}
}

This request returns the usual response, with a (possibly changed) token and a fresh
set of recommendations, which may be affected by the contents of the cart.
Similarly, if the shopper makes a purchase, this is useful information for the
recommendations service. The application should issue a request to the endpoint to
indicate that a checkout has occurred.

POST /pr/v4/sessions/click
{
"tenantId": "p01234567c1PRD", "token": "aaabbbcccddd", "catalogId":
"mysiteCatalog", "checkout": {
"products": [{ "productId": "p11879", "quantity": 1,
"price": 48.99
},{
"productId": "p02113", "quantity": 1,
"price": 35
}],

"totalPrice": 83.99, "pricelistGroupId": "sunnysideStore",

"currencyCode": "USD"
}
}

Commerce responds with the standard response with the token:

200 OK
{
"token": "aaabbbcccddd"
}

If an error occurs due to an invalid input, the response will include the HTTP 400
status code and a short, diagnostic message. These messages are not a part of the
API, and they are not intended to be displayed to shoppers. For example:

400 Bad Request

{
"token": "aaabbbcccddd",
"error": "Missing URL in view request."
}

7-60
 Chapter 7
Display product recommendations

Likewise, if there is an internal service error, the response will include the HTTP 500 status
code, and will not return a token. The most recently-returned token should still be used in the
next request. For example:

500 Internal Service Error

{
"error": "Something went wrong, ops has been notified."
}

If the shopper’s profile ID is known to the client application, you can pass it in the request as
a top level property. This allows for personalized recommendations for the user across
different clients, for example, a web browser and a custom headless application. If the user
has logged into the client application, each request can include the profile ID, as shown in
this example:

POST /pr/v4/sessions/click
{
"tenantId": "p01234567c1PRD", "token": "aaabbbcccddd", "catalogId":
"mysiteCatalog", "profileId": "p271123", "view": {
"url": "[Link] "pageTitle": "Mysite:
Red Shirt",

"referrer": "[Link] "productId": "p02113"

},
"recommendations": { "pdpRecs": {
"numRecs": 6,
"strategy": "inCollection"
},
"top": {
"numRecs": 4, "strategy": "topSellers"
}
}
}

In this sample request, the catalogId property is used when the Commerce instance has
multiple catalogs, for example, when the instance supports multiple brand sites or country
sites. The Recommendations engine uses catalogId to restrict recommendations to products
that are available only in the specified catalog.

Display product recommendations

Commerce includes a Product Recommendations widget you can use to provide automated,
personalized product recommendations to each shopper. The widget can be placed in any
layout, and the same widget instance can be shared over as many pages as necessary to
provide recommendations to your shoppers.

This section applies to Storefront Classic only.

This section describes how to use the Product Recommendations widget that is included with
Storefront Classic. Open Storefront Framework (OSF) also includes its own Product
Recommendations Carousel widget. This widget appears on the Product layout in blank-

7-61
 Chapter 7
Display product recommendations

store template that comes with OSF. For more information, see Develop and Deploy
Applications.
For information on including recommendations in emails your store sends, see
Customize Email Templates.
To display product recommendations in Storefront Classic:
1. Click the Design icon.
2. From the Layout menu, select the layout in which you want to provide product
recommendations.
3. Clone the layout to preserve the original layout for future use as a template. For
more information, see Design Your Store Layout.
4. Open the layout in grid view. Create any new rows as needed to accommodate the
widget.
5. From Components, drag and drop the Product Recommendations widget into
the layout in the location you want the recommendations to appear. You can create
a new widget instance or use an existing instance.
6. Making changes to widget settings is optional. Either accept the widget default
settings or click the Settings icon located on the widget instance to edit the widget
settings.
• Setting changes to Recommendations Title affects font styles and display
text for the widget. For information on changing the font, see Customize Your
Store’s Design Theme.
• The Recommendations carousel is where the recommendations are
displayed, affected by the number of recommendations to show, the strategy,
and the restriction. Additional conditions may affect the appearance of the
carousel. For example, a smart phone screen may display fewer
recommended products by virtue of its available screen size.
7. On the widget settings dialog, click Settings to make changes to maximum number
of product recommendations, strategies, restrictions, and collection(s). Changes to
widget settings are optional.
• Enter the maximum number of recommendations to appear in the widget
instance. The default is 12.
While the default is 12, the number of recommendations displayed to your
shoppers is based on strategies and restrictions as well as your catalog
configuration. Screen width also influences the number of recommendations
displayed in the widget instance at one time.
As a best practice, choose a number of recommendations so that all
recommendations can be viewed in the carousel with one or two clicks of the Next
button.
• Select the strategy, restriction, or collection(s) associated with the displayed
recommendations. For details about built-in and custom strategies, see
Configure AI Recommendations Rules
• Click Save.
The following table describes the restrictions you can apply to displayed
recommendations:

7-62
 Chapter 7
Add images to products

Manage personal data in product recommendations

The Product Recommendations widget collects personal data as defined by the EU General
Data Protection Regulation (GDPR). However, if you have configured your site to request
cookie consent, and the shopper has declined to provide that consent, the widget does not
capture or use personal data for the visit. Specifically, the Product Recommendations widget
checks for the existence of the GDPRCookieP13nConsentGranted cookie. If the cookie is
not present on the shopper’s browser, personal data is not collected. Cross-session
recommendations are not available for the shopper, and the Most Recently Viewed strategy is
not maintained for him or her. The shopper is thus treated as a new, unknown shopper for
each session.
For detailed information on how to configure your site to request consent, refer to Manage the
Use of Personal Data.

Add images to products

Use a product’s Media tab to upload and arrange product images that will appear on your
store.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You can upload JPG, BMP, PNG, and GIF files. Commerce automatically sizes your images
for display on different devices, such as laptops, tablets, and mobile phones.
Note: This section describes how to upload images to individual products. See Manage
Media for Your Store for information about using the media library, including information about
uploading a ZIP file of images and other types of media that are automatically assigned to
products and collections in your catalog.
This section includes the following topics:
• Add and assign images
• Manage images for variant values
• Add alt text and titles to images
• Reorder images
• Remove images

Add and assign images

If you upload multiple images, the first image displayed on the Media tab is used as the
primary image for the product. To see how images will be displayed on your store, go to the
Design page and select the Product layout. For more information about layouts, see Design
Your Store Layout.
To add an image to a product:
1. On the Catalog page, navigate to the product to which you want to add images.
2. On the product’s Media tab, click Add Images and select Upload New.
3. Select an image to upload.
You can upload only one image at a time. If you select a file with the same name as a file
you already uploaded, the new file replaces the existing one.

7-63
 Chapter 7
Add images to products

4. Click Save.
To assign an image to a product from the media library:
1. On the Catalog page, open the product to which you want to add images.
2. On the product’s Media tab, click Add Images and select Media Library.
3. Select images to assign to the product and click Add.
For details about selecting, sorting, and searching for images in the media library,
see Manage Media for Your Store .
4. Click Save.

Manage images for variant values

If you specified that product images should be displayed at the variant property value
level, you can assign a separate main image to the product for each value. For
example, you can assign a separate image to each color.
To manage images for variant values:
1. On the Catalog page, navigate to the product whose images you want to manage.
2. On the product’s Media tab, select a variant value from the drop down list.
By default, Always Shown is selected. This means that the same image is
displayed for each of the values.
Note: If you uploaded a ZIP file of images that were automatically assigned to the
product, those images are assigned to Always Shown. See Automatically assign
images to products and collections for more information.
3. To add an image for the selected value, click Add Images and select either
Upload New or Media Library.
4. Select an image to upload or assign.
You can assign more than one image to each value.
5. Repeat steps 2 through 4 for each value that requires images.
6. Click Save.

Add alt text and titles to images

Alt text and titles provide descriptions of images assigned to products and collections.
• Search engines index alt text and use it to return images for user queries. Alt text
is also used when shoppers cannot view images on the web. For example, a blind
shopper’s screen reader reads an image’s alt text when it reaches the image on a
category page on your store.
• A title is used as a tooltip, or hover text, when a shopper points to the image.
By default, Oracle Commerce uses a product or collection’s name for both the alt text
and title text for all images assigned to that product or collection. You can edit the
default alt text and title text on the product or collection’s Media tab.
Note: You can also add keywords, titles, and descriptions to products and collections.
See Add metadata to products and collections for more information.
To edit an image’s alt text and title:
1. On the Catalog page, open the product or collection whose image you want to
edit. Click the Media tab.

7-64
 Chapter 7
Create gift cards

2. Hover over the image and click the Edit current image icon when it appears. A new
screen displays containing the image properties.
3. To change the current Alt Text you must check Edit Manually and enter the new text in
the text box.
To change back to the default alt text, check Edit Manually and click Reset Default.
4. To change the current Title you must check Edit Manually and enter the new one in the
text box.
To change back to the default title, check Edit Manually and click Reset Default.
5. Click Save.

Reorder images
The first image displayed on a product’s Media tab is used as the primary image for the
product on your store. The remaining images are displayed on the product details page in the
order they appear on the Media tab.
To reorder images:
1. On the Catalog page, open the product whose images you want to reorder. Click the
Media tab.
2. To make an image the primary image for the product, do either of the following:
• Drag the image to beginning of the list.
• Hover over the image and click the star icon when it appears.

Remove images
When you remove an image from a product, you cannot access it again with the Commerce
tools. If you remove the primary image, the next image on the Media tab becomes the
primary image. If you remove all images from a product, a placeholder is displayed on your
store.
To remove an image from a product:
1. On the Catalog page, navigate to the product whose images you want to remove.
2. On the product’s Media tab, select an image click the X icon when it appears.
Tip: To remove multiple images, select all the images you want to remove and then click
the X icon on any of them.
3. Confirm that you want to remove the selected images.

Create gift cards

This section describes how to add gift cards to your catalog.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You create a gift card just as you do any other product in your catalog. This release of
Commerce does not support electronic gift cards. You can sell only physical gift cards that
are shipped to shoppers. See Integrate with a Gift Card Payment Gateway for information
about integrating with a gift card payment provider to enable shoppers to use gift cards to
make purchases on your store.
To add gift cards to your catalog:

7-65
 Chapter 7
Manage inventory

1. (Optional) Create a collection for gift cards. You can also add your gift cards to any
existing collection in your catalog.
2. If your store sells different styles of gift cards, create a new product type for gift
cards. You will use the product type to add variant properties for the different types
of cards or envelopes you want to offer. For example, the variant property Card
Style could have the values Classic, Happy Birthday, and Congratulations.
If your store sells only one style of gift card, you do not have to create a product
type. Simply use the base product type.
For more information, see Create and edit product types.
3. Create a new product with the Gift Card or base product type.
The List Price property specifies the gift card’s denomination. You must create a
separate product for each denomination. For example, if your store sells gift cards
in $25, $50, $75, and $100 denominations, you must create four gift card products.
For more information, see Create and work with products.
4. Create SKUs for each gift card. For more information, see Create and work with
SKUs.
5. Add images for the gift cards. For more information, see Add images to products.
6. (Optional) If your store uses a branded name for your gift cards, you can replace
the phrase “gift card” with that name in places like your checkout page. For more
information, see Customize your web store's text.

Manage inventory
By default, Commerce maintains one set of inventory values for each SKU.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This section describes how to view and update the inventory and stock threshold for
each product and SKU in your catalogs. Additionally, you can use the Commerce
Admin API to perform the following inventory tasks:
• Manage preorder and backorder counts and thresholds. See Manage Inventory for
Preorders and Backorders for more information.
• Maintain inventory for specific locations, such as stores and warehouses. See
Manage Multiple Inventory Locations for more information.
Important: The inventory list includes both published and unpublished products. You
do not have to publish inventory changes. Changes you make to inventory for
published products are immediately visible on your store. Changes you make to
inventory for new (unpublished) products will appear on your store with the rest of the
product information the next time you publish changes.
To add or update inventory:
1. On the Catalog page, click Manage Catalogs, then select Inventory.
The Inventory page is empty until you search for products or SKUs.
2. In the search box, type or paste full or partial product names, SKU IDs, or both.
• Separate multiple entries with commas.
• You can mix names and IDs in the same search.

7-66
 Chapter 7
Manage inventory

• The search will not start if you enter just a comma, even if your catalog includes
products whose names include commas.
• There is a limit of 1000 characters and 200 search terms, whichever comes first. If
there are more than 200 search terms, all terms past 200 are ignored. If there are
duplicate IDs, any ID past the first is ignored.
Commerce displays the following inventory details for each product or SKU:
• Inventory count: The number of items that are physically in stock.
• Stock threshold: A value you specify that indicates when an item should display as
out-of-stock on your storefront. An item is considered out-of-stock when the inventory
count is less than or equal to the stock threshold value.
• Status: Icons that specify if a SKU or product is out-of-stock or if a product includes
some SKUs that are out-of-stock.
3. Double-click the SKU's inventory count and enter a new value. You must enter an integer.
Press Enter to save the new value and move to the inventory count of the next SKU in
the list. You can also click somewhere else on the page to save the new value without
moving to the next SKU.
4. (Optional) Double-click the SKU's stock threshold and enter a new value. You must enter
an integer.
Press Enter to save the new value and move to the stock threshold of the next SKU in
the list. You can also click somewhere else on the page to save the new value without
moving to the next SKU.
Note: You can quickly make a number of inventory changes at once by importing them. For
more information, see Import and Export Catalog Items and Inventory.

Customize inventory status messaging

You can view and update the inventory status message that displays to your shoppers. The
messaging displayed to shoppers is configurable , as follows:
1. Open the Design page and click the Layout tab.
2. Open the Product layout and click the Grid View option.
3. Locate the Product Details widget and open the Settings icon, visible on the top right
corner of each widget.
4. Click the Layout option to display the elements and select Inventory Status.
You can now see the Product Details widget inventory status tabs, allowing you to
customize the messaging displayed for each of the different statuses:
• In Stock
• Out of Stock
• PreOrder
• BackOrder
5. Add your message to the relevant inventory status.
6. Customize the message settings, and preview.
7. Click Done to save your configurations, and Save to exit the widget settings.

7-67
 Chapter 7
Preview your changes

Preview your changes

Before you publish any changes, preview them so you can see how they will appear
on your live store.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

To launch a preview session at any time, click the Preview button. The preview
session launches in a new browser tab or window. If your instance supports more than
one store, select the store to preview from the drop-down list at the top of the preview
window. To end the preview session, simply close that tab or window.
Nothing you do in a preview session affects your production storefront.
You can apply the following settings to a preview session:
• Audience shows how the store looks to specific groups of shoppers.
• Account shows how an account-based store looks to shoppers associated with a
specific account.
• Date shows how the store looks at a specified future date and time.
• Viewport shows how the store’s pages look on different devices, such as desktops
and mobile phones.

Preview a store by audience

Audiences help you target content to certain groups of shoppers. Previewing a store
as a member of an audience shows how the store looks to a shopper who is a
member of the audience. See Define Audiences to learn how to create and use
audiences.
To preview a store as the member of an audience:
1. Click the Preview button to launch a new preview session in a new tab or window.
2. Click the Site Preview Settings icon.
3. On the Display tab, click the Audience box and select an audience from the list.
You can filter the list by typing or pasting some text in the Audience box.
4. You can add more than one audience, but you can select only one at a time.
5. Click Apply.
If you select a disabled audience, Commerce treats it as enabled during the preview
session.
If you select more than one audience, Commerce displays the content based on the
priority of each audience assigned to a content variation slot. See Customize slotsfor
more information.

Preview a store by viewport

Previewing a store by viewport lets you see how the store’s pages look on different
devices, such as mobile phones, tablets, and laptops.
To preview a store by viewport:

7-68
 Chapter 7
Preview your changes

1. Click the Preview button to launch a new preview session in a new tab or window.
2. Click the Site Preview Settings icon.
3. On the Display tab, select a viewport breakpoint to preview.
XS (extra small resolutions)
SM: (small resolutions)
MD: (medium resolutions)
LG: (large resolutions)
4. Click Apply.

Preview a store by date and time

Previewing a store by date and time lets you see how the store’s pages look if your changes
were published at a future date and time. The date and time filter allow you to view the
following types of content:
• Promotions and promotional content scheduled for a future date and time.
• Widgets configured in slots against a future date and time.
Commerce evaluates preview dates and times based on the date and time on the server.
To preview a store by date and time:
1. Click the Preview button to launch a new preview session in a new tab or window.
2. Click the Site Preview Settings icon.
3. In the Date field, click the calendar icon and select a date. Click the clock icon to set the
hour, minute, and AM/PM portions of the time. .
4. Click Apply.

Preview an account-based store

Previewing an account-based store lets you see how the store looks to shoppers associated
with different business accounts.
Commerce allows you to create accounts for companies that do business with you, such as
manufacturers, distributors, and wholesalers. Each account represents a single organization
and a unique customer.

For more information about account-based stores, see Configure Business Accounts.

7-69
8
Manage SEO
Search Engine Optimization (SEO) is a term used to describe a variety of techniques for
making your store’s pages more accessible to web spiders (also known as web crawlers or
robots) used by Internet search engines to crawl the Web to gather pages for indexing.
The goal of SEO is to increase the ranking of the indexed pages in search results, and to
make sure shoppers view the pages you want them to see when they search. The topics in
this section describe several SEO techniques and the built-in tools that Commerce provides
for implementing them.

Configure URL patterns

In Commerce, you can customize the URL structure of your store’s Collection and Product
pages so they mirror your SEO strategies.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This section includes the following topics:

• Plan URL patterns
• Understand default URL patterns
• Customize URL patterns

Plan URL patterns

Keep the following points in mind as you plan your URL patterns:
• It is best to customize URL patterns when you are planning and testing your store. If you
change a URL pattern on your production storefront, you must specify a URL redirect for
that pattern. Otherwise, older bookmarked URLs will display an error page instead of the
pages you intended.
• Each URL pattern must be a valid URL for the page type (Collection or Product) and
must contain only components that are valid for the page type. For example, if you
include the variable {brand} in the Collection pattern, you will not be able to save your
changes because brand is not a collection property.
• Each URL pattern uniquely identifies each product and collection via id numbers, or, you
can use the URL slug to enter descriptive terms. For example, /product/
{=seoUrlSlugDerived}
– descriptive URLs for categories may not be required as, by definition, categories
should already have distinctive unique names.
– descriptive URLs for products may be necessary as products can have similar names
(slugs) and could, therefore, benefit store maintenance.
• Each URL pattern can contain up to 254 characters and cannot contain spaces or special
characters except – (dash).

8-1
 Chapter 8
Configure URL patterns

• It is best to plan URL patterns bearing in mind that each URL must be unique. This
is necessary in order to avoid storefront display issues, such as, 404 errors, or the
wrong collection being displayed.
Keep the following points in mind as you plan your URL patterns and your Commerce
instance supports more than one language:
• Commerce automatically creates URL patterns for each supported language.
Commerce uses your catalog translations for the variables values, but you must
manually translate any words that are not variables. For example, in the default
product page URL pattern, you must manually translate the word product. For
more information, see Localize Your Store.
• Although it is possible to configure a different product and collection page URL
pattern for each language supported by your site, it is recommended to maintain
URL pattern consistency between each language. This allows you to translate any
fixed parts you many have in your URL patterns for each language.
• There is a language prefix (a language subdirectory) that is automatically included
for each additional language supported by your site. This subdirectory is not
included in the default language URL structure for a multi-lingual site. For
example, if you support 3 languages for your site: English, Spanish, and French,
with English being the default language, your URL structures will be as follows:
English URLs: [Link]/my-url-patterns

Spanish URLs: [Link]/es/my-url-patterns

French URLs: [Link]/fr/my-url-patterns

Understand default URL patterns

By default, Commerce uses the following URL patterns for Category and Product
pages:
• Collection page: /{seoTitleDerived}/category/{id} For example, /
cameras-and-camcorders/category/cameracat.
• Product page: /{seoTitleDerived}/product/{id} For example, /
striped-button-down/product/prod10001.
Understand URL slug patterns
Clicking the Build URL Slugs button generates a URL mapping table, allowing the
slug value to be used as a unique url pattern identifier instead of the {id} property.
This enables you to define the URL patterns with a descriptive slug value, prefixed
with ‘=’. The ‘=‘ symbol is used with the seoUrlSlugDerived pattern only and ensures
that the specified products and collections are returned from the server, as highlighted
below:
• Collection page: /category/{=seoUrlSlugDerived}, for example /
category/cameras-and-camcorders.
• Product page: /product/{=seoUrlSlugDerived}, for example, /product/
samsung-f90bn-hd-flash-memory-camcorder.

Customize URL patterns

To customize URL patterns for your store:

8-2
 Chapter 8
Configure URL patterns

1. Click the Settings icon.

2. Select Setup and then click the URL Patterns tab.
3. If your Commerce instance runs multiple sites, pick a site to configure from the list at the
top of the settings list. See Run Multiple Stores from One Commerce Instance for more
information.
4. Click the Collection Page URL.
5. Type the new pattern and click the Save icon when you are done. Note: URL slug values
must be unique, if not, a warning message is displayed indicating that this must be the
case.
Variables must be inside {} (curly braces, for example, {id} or {seoTitleDerived}). For a list
of variables for Collection Page URLs and Product Page URLs, see the tables that follow
this procedure.
6. (Optional) Check the Auto Redirect box so that shoppers who have bookmarked older
URLs are automatically redirected to the new URL. Auto Redirect is selected by default
and will only redirect from the default URLs, not from previous patterns.
7. If you want to use URL slugs rather than IDs in your URLs, you will need to click the
Build URL Slugs button.
8. (Optional) You can simplify your URL slugs by clicking the Build URL Slugs button. You
will notice that the most recent date and time the URL slug table was built is displayed.
Simplifying URL slugs removes any special characters, replaces spaces with hyphens,
and simplifies into lowercase. Once the simplified URL slugs have been built, you will
need to manually update the URL pattern to use the new URL slug. For example, "/
product/{=seoUrlSlugDerived}".Note: If a warning displays informing you that URL slugs
are not unique, then a uniqueness check can be performed in order to fix this issue. See
Perform uniqueness checks for URL patterns for details.
9. Click the Product Page URL and repeat steps 4 – 6 to update the URL pattern for the
product page.
10. Check if the URL pattern was changed by clicking through your store. You may also wish
to check that redirected URLs work correctly.
The following table describes the available properties for Collection Page URL patterns. Each
property displays the value of the corresponding collection property. For more information
about collection properties, see Organize products in collections.

Collection Page URL Variable Description

displayName The collection’s Name property. (A short,
descriptive name that identifies the collection.)
Id The collection’s ID property. (The ID that identifies
the collection internally.)
Description* The collection’s Description property. (A short
description to display with the collection.)
parentCategory The display name of the collection’s current
parent.
seoDescriptionDerived* The collection’s Meta Description property. See
Add metadata to products and collections for more
information.
seoTitleDerived* The collection’s Title Tag property. See Add
metadata to products and collections for more
information.

8-3
 Chapter 8
Configure URL patterns

Collection Page URL Variable Description

seoUrlSlugDerived The collection’s URL Slug property. See Add
metadata to products and collections for more
information.

* These variables should not be used as queryable elements in URL patterns (that is,
they are not included in Build URL Slugs).
The following table describes the available properties for Product Page URL patterns.
Each variable displays the value of the corresponding product property. For more
information about product properties, see Understand the base product type.

Product Page URL Variable Description

displayName The product’s Name property. (A short,
descriptive name that identifies the product.)
Id The product’s ID property. (The ID that
identifies the product internally.)
Description* The product’s Description property. (A short
description to display with the product.)
parentCategory The display name of the product’s current
parent collection.
Brand The name of the manufacturer.
Type The product type. If the product was created
with the Base product type, this value is not
displayed. See Create and edit product types
for more information.
seoDescriptionDerived* The product’s Meta Description property. See
Add metadata to products and collections for
more information.
seoTitleDerived* The product’s Title Tag property. See Add
metadata to products and collections for more
information.
seoUrlSlugDerived The product’s URL Slug property. See Add
metadata to products and collections for more
information.

* These variables should not be used as the elements in URL patterns.

Perform uniqueness checks for URL patterns
The uniqueness of URL patterns plays a significant role in ensuring your site does not
encounter storefront display issues, such as 404 errors or the wrong collection being
displayed. Therefore, you must ensure the URL patterns used produce unique URLs
for each product and category.
It is worth noting that the uniqueness check for URL patterns is required only when
you have clicked the Build URL Slugs button and you are using {=seoUrlSlugDerived}
in your URL pattern.
You can use the Catalog export file to check that categories and/or products do not
have a shared URL slug value. To do so:
1. Go to Catalog and click the Export button to export the Catalog data.

8-4
 Chapter 8
Customize SEO tags

2. Select the item you wish to export and click Export. This exports the data in the form of
an Excel spreadsheet.
3. Open the Excel data.
4. Scroll to the seoUrlslugs column and sort alphabetically.
The seoUrlslugs column may not contain any data; this happens only when URL slugs
have already been built.
5. Identify instances that are identical, and do one of the following:
Either
6. Edit the values for the duplicated seoUrlslugs within Excel, and click Save. You must
then click Import, choose the edited file, and click Upload File. Click the Validate button to
confirm.
Or
7. On the Catalog page, open the product with the duplicated URL and go to the Metadata
tab. To change the current information, check Edit Manually and enter the text within
each box. You can change back to the default alt text by checking Edit Manually and
clicking Reset Default.
8. Click Save.
Note: The uniqueness check procedure is automatically performed when the Build URL
button is clicked, producing a list of duplicates via the API response. However, you can
continue to perform the above procedure as required.

Customize SEO tags

Commerce provides the option to modify meta tag patterns, or customize the meta tags on
any static page. Meta tags are placed within the code of your web store pages and provide
additional information to the search engine. They control how, and suggest what, results get
displayed in the search results.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Web search engines partly base their rankings of pages on the words that appear in certain
HTML tags, particularly <meta> tags and the <title> tag.

A common SEO technique is to list key search terms in those tags in order to raise the
ranking of the pages for those terms. While you should avoid “keyword stuffing” – that is,
overloading tags with content and keywords that are not helpful for shoppers, especially
keywords that have nothing to do with the content of your store – you can customize these
tags.
This section includes the following topics:
• Tag store pages
• Customize URL slugs
• Tag metadata for images
• Add Open Graph tags to product and wish list pages

Tag store pages

Meta title and meta description optimization play a vital role in SEO as both elements are
displayed in the search results. The meta title tag is taken into consideration in the ranking

8-5
 Chapter 8
Customize SEO tags

process. The meta description is used by Google in Search Engine Results Pages
(SERPs) snippets, and may encourage users to click on your page, thereby potentially
impacting your click-through rate.
Commerce automatically adds <title>, <meta name="keywords">, and <meta
name="description"> tags to the headers of several types of pages on your store.
For each product and collection page in your store, Commerce sets the default values
of SEO tags to the following:
• <title> tag: The value of the Name property of the product or collection.
• <meta name="keywords"> tag: The values of the Name and Parent Collection
properties of a product. The values of the Name and Selected Parent properties of
a collection.
• <meta name="description"> tag: The values of the Name and Description
properties of the product or collection.
You can customize the metadata for these tags when you edit a product or collection
on the Catalog page in the administration interface. To learn how to customize the
metadata that Commerce automatically turns into tags, see Add metadata to products
and collections.
For content pages, such as the home page and article pages on your store,
Commerce sets the default values of SEO tags to the following:
• <title> tag: The value of the Site Name property.
• <meta name="keywords"> tag: By default, there is no metadata in this tag.
• <meta name="description"> tag: By default, there is no metadata in this tag.
You can customize the metadata for these tags when you edit a layout on the Design
page in the administration interface.

Customize URL slugs

A URL slug is the SEO-friendly, human-readable part of product and collection page
URLs. Commerce automatically creates a URL slug for each product and collection
page that is set to the value of the Name property for the product or collection.
You can customize the URL slug when you edit a product or collection on the Catalog
page in the administration interface. For example, you could edit the slug to exclude
special characters that can cause problems for robots that index your pages, and re-
test to see if the problems reoccur. To learn how to customize a URL slug, see Add
metadata to products and collections.

Tag metadata for images

An alt attribute attached to an image file helps search engines understand what the
image shows, and rank it in the image search. Images can deliver a significant part of
site traffic so it is worthwhile to use descriptive:
• file names - rename the file before uploading to the Commerce, for example, red-
[Link] is better than [Link].
• alt attribute - a few words describing what the image presents. Alts and title
attributes can be customized via a bulk CSV upload.
Commerce automatically adds alt text and title attributes to the <img> tag for each
image on a product or collection page on your store.

8-6
 Chapter 8
Manage SEO content

• Search engines index alt text and use it to return images for user queries. Alt text is also
used when shoppers cannot view images on the web. For example, a blind shopper’s
screen reader reads an image’s alt text when it reaches the image on a category page on
your store.
• A title is used as a tooltip, or hover text, when a shopper points to the image.
By default, both attributes are set to the value of the Name property for the product or
collection. You can customize the alt text and title when you edit a product or collection on the
Catalog page in the administration interface. See Add alt text and titles to images for more
information.

Add Open Graph tags to product and wish list pages

The Product Social Meta Tags widget automatically adds Open Graph (OG) protocol meta
tags to product pages to control the content displayed when a page is shared on Facebook.
To learn how to customize the Product Social Meta Tags widget, see Share using email,
Facebook, Pinterest, or Twitter and Product Social Meta Tags.
You can add custom tags to the header of any page by creating them in the Additional Meta
Tags section of the page layout. To learn how to customize metadata for page tags, see
Design Your Store Layout.

Manage SEO content

Commerce enables you to manage the SEO content within your store by providing
configurable title and meta descriptions, headings, category and product descriptions,
accessible content, and product variants.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Generate title/meta description

Commerce provides auto generated title and meta descriptions for the display name, brand
name, and body content of your store. You can configure patterns based on default or custom
fields for each page type, with each static page displaying a preview of how your page
snippet will look in search results.
Duplication of SEO tags, where the same title or meta tag value is propagated across pages
of a given type, should be avoided. It is good practice to customize your homepage title and
meta description as title tags are taken into account in organic rankings. Whilst meta
descriptions suggest to Google what should be displayed in an organic snippet. To optimize
your meta descriptions you should highlight product features for a higher click through rate.

Headings
Commerce supports unique heading tags (H1-H6) on each page type. The heading tag
default settings are:
• <h1> - product/category name or page title
• <h2> - your product or category description field value
• <h3> - inside the main unique body content; not to be used for repetitive site-wide
widgets
• <h4> - <h6> tags are used in the remaining site-wide page elements (such as reviews,
similar products, etc.)

8-7
 Chapter 8
Manage SEO content

When planning heading tags for your Commerce site, keep in mind the following
points:
• place primary keywords inside H1 headings, secondary keywords are allocated in
H2 headings.
• H1-H2 tags with the highest importance should be unique. Therefore, it is
advisable to make key headings different from the page title. In particular, H1-H2
tags should be planned out for the homepage, product, category, and static article
pages.
• customize the H1-H6 placements directly within in the widget source code.
• avoid constraining heading placements with CSS styling.
• ensure heading tags do not make any changes in page layouts.

Category/product descriptions
Each category or single product page should have a unique description as it is
recommended to tailor your site copy without duplication from the product details. For
example, category descriptions can be placed at the bottom of the page to achieve
usability on mobile and for the benefit of SEO.

Content accessible to web crawlers

To aid accessibility on mobile devices, ensure your most relevant content is instantly
visible once a user lands on a page. Copy hidden under a “see more” link, or beneath
tabs, must be present in the prerendered version of the page.
To view the DOM of a prerendered page:
1. Open Chrome Developer Tools and navigate to the Network tab.
2. Switch the User-Agent to Googlebot and reload the page.
3. Click on the Elements tab. You will see the prerendered version of DOM. Note: If
you use onClick or onScroll events to load additional content on the page, it will
not be included in the prerendered version of DOM.
4. Search the DOM to check if the content has loaded. Note: If you use video or
images, it is recommended to always provide captions, ALT/TITLE attributes and
transcriptions for video content.

Product variants
Multiple variants of the same product should be published under one URL page to
avoid duplicate content issues. This is the case when there is little that differentiates
the product - such as color, size, pattern, etc. It is also recommended to use drop
downs and selectors to help shoppers pick their product features on a single product
page. Sizes are most often implemented as a drop down with a URL that does not
change, or with a parameter added to create a URL canonicalized to the primary
product URL.
For instances when a product type may be perceived as two different items, products
can be submitted as separate indexable URLs, especially if a shopper is more likely to
use the variation of the product in their searches. For example, a product such as an
eyeshadow with two unique variant names would be two different items. In this case,
each variant = unique indexable URL. You may want to consider the number of
potentially duplicate product variants that can result from adding separate indexable
URLs for each variant.

8-8
 Chapter 8
Understand canonical tags

Understand canonical tags

Each of your web store pages has a canonical link (or tag) embedded within the head section
code. This link signals the source, or original, URL of a page to search engines.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Use canonical links

When a given page on your web store can be accessed via several URLs, then the canonical
link indicates to search engines which version of that page is the original version. This is also
the case when there are multiple pages with different URLs containing only slight content
variations.
The use of canonical links within your web store pages improves search engine rankings as
search engines use them to consolidate links to duplicate, or similar, content. This means
they assign a higher ranking value to those pages marked as the source URL.
An example of how this may look on your site is outlined below.
Say a robot lands on the following link:
[Link]

In the <head>, this page might include the canonical URL

<html>
<head>
<link rel="canonical" href="[Link]
mens_shoes">

If a robot follows a link somewhere that lands the same page, but with a different address,
such as:
[Link]

The canonical URL would point to the first category.

<html>
<head>

<link rel="canonical" href="[Link]

mens_shoes">

Use canonical and pagination tags

Commerce provides two different pagination layouts: numeric (default), or rel="next" and
rel="prev" links.

For the first page in a sequence on the numeric pagination layout, you will see a normal
request for the category page and a request for page zero of the sequence. Zero should be
used to display the first batch of content on the product listing pages. All canonical tags on
paginated pages in a sequence should be self-referential, so the URLs might look like
[Link]/category/c1234, [Link]/category/cshoes/2,

8-9
 Chapter 8
Utilize widgets for SEO

[Link]/category/c1234/3, and so on. The rel=canonical attribute

for “/1” will point to the page zero category page URL.
If the page type is ‘Article’ then a non-parameterized self-reference is added.
Each shopping and article page contains a <link> element with the attribute
rel="canonical". If the page type is:

• ‘Home’ then the canonical attribute points to [Link]

• ‘Product’, then a self-reference is added to the non-parameterized version of that
product detail page.
• ‘Collection’, then canonical elements are added based on whether or not the listing
includes pagination, as described earlier: page zero, page /2, page /3, and so on.
The pagination layout with the HTML attributes rel="next" and rel="prev" indicate to
search engines that the relationship between individual URLs should follow a logical
sequence. These are automatically added when there is more than one page
displaying items from one Collection.
If there is a previous page in the sequence, you will see the rel="prev" element
referring to the previous page.
If there is a next page in the sequence, you will see the rel="next" element referring
to the next page.
Therefore, aside from page “zero” and the last page in a given sequence, all in-
between compound pages will contain both rel=”prev” and rel=”next”.
Making changes to your pagination configurations can result in some of the
subsequent URLs being inaccessible to search engines. For example, you may want
to use an infinite scroll to load additional items in a Collection, however, search engine
crawlers do not scroll so everything that appears after an event of scrolling will not be
discovered by the crawler. Therefore, you should not remove your pagination links
from mobile views, and prior to your site launch you should always verify they work.
The numeric pagination layout provides optimal SEO for all store types, whereas the
rel="next" and rel="prev" links work best where there are 1 or 2 paginated pages.

Use canonical and language tags

When at least one additional storefront language exists, then the 'hreflang' tag is
added to all pages. Regardless of whether a multi-lingual store uses directories or
subdomains, 'hreflang' annotations must be used as these signal the relationship
between multi-lingual sites. Canonical tags across different language sites should
always be self-canonical.

Utilize widgets for SEO

You can use several of the widgets within Commerce's Design page to facilitate SEO.

This section applies to Storefront Classic only.

This section includes the following topics:

• Customize the Page Not Found widget
• Utilize the Pop-up Stack widget

8-10
 Chapter 8
Utilize widgets for SEO

• Optimize the Breadcrumbs widget

• Optimize widgets on mobile screens
• Understand meta robot tags in widgets

Customize the Page Not Found widget

Web sites display Error 404 pages when a page cannot be found on the server, for example,
if a shopper tries to access your store with a bookmarked URL for a product your store no
longer carries.
Commerce uses the Page Not Found widget to display a message to the shopper that the
page they searched for has not been found. (This widget is available for the Error layout.) You
can benefit from adding links to other category pages within the message, for example,
include deep links to the most popular collections.
Note: There is a unique URL for each of the page layouts, providing a direct link to the
individual layout previews without the need to navigate from the Layout tab.
Customizing the Page Not Found widget and Error layout can help reduce site abandonment
when shoppers reach your error page. Make sure the page reflects your store’s branding and
includes links to other pages, such as bestselling products (see Display product
recommendations for more information), the store’s home page, or important categories.
To learn how to customize layouts and widgets, see Customize your store layouts.

Utilize the Pop-up Stack widget

The Pop-up Stack widget’s modal windows appear when a user interacts with your site.
Commerce's platform prevents pop-up messages or loaders from being included in the
prerenders, consequently these are not shown to Googlebot or other web crawlers.
You should consider the appearance of pop-up windows on user interaction (events like
clicking or scrolling) and their potential impact on decreasing the bounce rate and user
frustration. Test your pop-up widgets and ensure:
• multiple modal windows are not triggered at the same time.
• modal windows can be easily dismissed.
• the visibility of key body content on the landing pages is not obscured.

Optimize the Breadcrumbs widget

The Breadcrumbs widget is available for category and product pages, and can also be
enabled for static pages. Breadcrumb navigation reflects the dependencies between pages
and helps to better understand the structure of those pages, usually containing links.
Breadcrumbs should always be visible for mobile view. To improve usability, they can be
moved to the bottom of the page, beneath the product/category descriptions. It is advisable to
test breadcrumbs on various tablet and mobile resolutions and decide which placement
works best for your site.

Optimize widgets on mobile screens

As mobile screens limit the ability for all of the page widgets to be visible, you should ensure
the following elements (widgets) are always present on smaller resolutions:
• deep menu links (for example, via drop down menus) - shoppers must be able to drill
down through the category hierarchy tree

8-11
 Chapter 8
Understand SEO snapshots

• breadcrumbs - can be allocated above/below product listings

• pagination links - infinite scroll can be added on top of numeric links to compound
pages in a sequence
• page heading
• category descriptions
• product descriptions
Note: Commerce generates HTML prerenders as responsive. The same snapshot
code is served to both Googlebot mobile and desktop. Mobile-first indexing means that
Googlebot mobile will be decisive in organic rankings. You should be aware that
although the elements will be accessible for crawling for Googlebot mobile, parity
between crucial page elements being rendered on both mobile and desktop must be
assured.

Understand meta robot tags in widgets

Several widget types contain a default meta robot 'noindex' tag which prevents them
from being indexed, but are still accessible to web crawlers. Content pages, such as
wish lists, are set to 'noindex'. It is not recommended to change the directives for
those subdirectories. If a page is set to 'noindex' that page will no longer be available
in the search results.
You can choose between meta robots 'index,follow' and 'noindex,follow' on a
per page basis, as well as revoke the default 'noindex' on a directory level.

Note: Unlike canonical tags, which provide suggestions only, a meta robots tag is a
directive that is always followed by search engines.

Understand SEO snapshots

SEO generates static snapshots every 24 hours or whenever changes are published.
These snapshots provide a prerendered copy of a storefront page. However, as
Commerce does not have control over how often a crawl happens, search engine
results are not guaranteed to reflect the latest changes.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

All key SEO settings from your client side rendered store are mirrored when OCC
scripts generate HTML snapshots of your site, so you can be sure that signals sent to
search engines are consistent. The default setting ensures prerendered snapshots are
served to Googlebot and other search engine bots. However, you can modify your
preferences and decide whether JavaScript client side rendered, or HTML, snapshots
should be served to other crawlers.
As Commerce uses a JavaScript framework it is worth noting that all search engines
have some limitations in terms of processing JavaScript and rendering JavaScript-
heavy pages. In order to help search engines with crawling and indexing, Commerce
renders the page and static snapshots of your pages directly to the search engine
crawlers. These snapshots provide a prerendered copy of a storefront page.
Prerendering aims to speed up the indexing of fresh content published in your store,
such as, new product or collection pages.
Search engines (such as Google) regularly update URL information based on a strict
timeout. When pages are provided to Google after the timeout, the request is canceled

8-12
 Chapter 8
Configure URL redirects

and the page is not updated. Therefore, Commerce uses prerendered snapshots in order to
ensure storefront pages are delivered to Google as quickly as possible.
Commerce generates an already-rendered version of a storefront URL and stores a static
copy of the page (excluding dynamic elements or JavaScript) on the server to ensure a fast
retrieval. Note also that Commerce generates distinct snapshots for both mobile and desktop.
Your store's key SEO settings are mirrored when Commerce generates HTML snapshots of
your site, ensuring that signals sent to search engines are consistent. The default setting
ensures prerendered snapshots are served to search engine bots. However, you can modify
your preferences and decide if JS client side rendered, or HTML snapshots should be served
to other crawlers.

Configure URL redirects

You can configure URL redirects for your site that specifically relate to 301 and 302 browser
response codes, indicating that your redirected URL has either permanently or temporarily
moved, respectively.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

In the case of a 301 redirect, the URL is moved to a new target permanently. This type of
redirection can help with moving the SEO authority from the old URL to the new equivalent.
The following example illustrates a 301 redirect with an example site base URL:
[Link]/example with the redirection rule:

• originUrl: /smartphones/collection/id1234?show=all
• targetUrl: /fr/smartphones/collection/id789?show=20
It is worth noting that 302 redirects are the preferred choice if you want to redirect a page for
a limited amount of time.
URL redirects are created/deleted using the createRedirect and deleteRedirect endpoints
in the Admin REST API. The total number of entries in the database defaults to 1 million.
Should you require more than that, please contact Oracle Support.
URL redirection rules can be setup on a per site basis as each of the URL redirects are
relative to the site base URL. If a siteId is not provided, then the rule acts as a global
redirect for all sites. The following table describes the properties for redirecting URLs:

Parameter Description

originUrl Origin URL of the redirect.

siteId ID of the site to which the redirect belongs.

type Redirect type (301 or 302).

targetUrl Destination URL of the redirect.

Query parameters are not copied from the origin to target URL, instead you are required to
include them in the definition of the redirect rule. When deleting a URL redirect, you specify
the ID of the rule to delete using the path parameter of the deleteRedirect endpoint. For
example: DELETE /ccadmin/v1/redirects/30001.

8-13
 Chapter 8
Edit the [Link] file

The following example illustrates a 301 redirect:

POST /ccadmin/v1/redirects HTTP/1.1

Authorization: Bearer <access_token>
Content-Type: application/json
{
"originUrl": "/smartphones/collection/id1234?show=all",
"siteId": "siteUS",
"type": 301,
"targetUrl": "/fr/smartphones/collection/id789?show=20"
}

See the Oracle Commerce REST API documentation in the Oracle Help Center for
more information.

Edit the [Link] file

The [Link] file controls how web robots access and index your store’s pages.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

For more information about [Link] and the Robots Exclusion Protocol, visit
[Link].
If you run multiple sites within a single instance of Commerce, each site has its own
[Link] file. See Configure Sites to learn how to create multiple sites.

To view your store’s current [Link] file:

1. Enter the following URL into your browser:

[Link] url]/[Link]
where [store url] is the base URL for your store.
2. Commerce displays the contents of the current [Link] file.
If you run multiple sites and keep language versions in directories, for example,
[Link]/de/, [Link]/es/, you do not need to create a separate [Link] file
for each version. This is only the case for multiple sites over sub domains.
The Commerce [Link] file below shows the updated contents after these
recommendations have been made:

User-agent: *
Disallow: /cart
Disallow: /en/cart
Disallow: /checkout
Disallow: /en/checkout
Disallow: /profile
Disallow: /en/profile
Disallow: /searchresults
Disallow: /en/searchresults
Disallow: /confirmation
Disallow: /en/confirmation
Disallow: /wishlist_settings
Disallow: /en/wishlist_settings

8-14
 Chapter 8
Edit the [Link] file

Disallow: /wishlist
Disallow: /en/wishlist

Sitemap: [Link] url]:8080/[Link]

User-agent: * means that the exclusion rules should apply to all robots. You can replace the *
(asterisk) with the name of a specific robot to exclude, for example, Googlebot, or Bingbot.
Each Disallow: /[page] entry indicates a page that robots should not visit. You should not
remove any of the Disallow: entries from the default [Link] file, though you might want
to include additional pages that you want robots to ignore. If you are testing your store and do
not want any robots to crawl any pages, you might want your [Link] file to look like this:

User-agent: * Disallow: /

If you plan to use your staging site as your production site when development and testing is
complete, you will need to change the content in the [Link] file to the custom settings
presented above. If you tested on a separate staging domain, Commerce inputs a valid
default [Link] for you for your production storefront when you go live.
You cannot edit the [Link] file in the administration UI. You must edit it with the Commerce
Admin REST API. See Use the REST APIs for information about the REST APIs.
To update the [Link] file, issue a PUT request to /ccadmin/v1/merchant/
robots. The body of the request must include the entire contents of the file, in text/plain
format.
When you update the [Link] file, it will not be overwritten until the next PUT request is
sent to /ccadmin/v1/merchant/robots.

If you run multiple sites within a single instance of Commerce, you must specify the site
whose [Link] file you are updating in the x-ccsite header in the PUT request. If you do
not specify a site, the request updates the default site’s [Link] file.

The following example shows a PUT request that adds your error page to the list of pages for
robots to ignore.

PUT /ccadmin/v1/merchant/robots HTTP/1.1

Content-Type: text/plain
Authorization: Bearer <access_token>

{
User-agent: *
Disallow: /cart
Disallow: /checkout
Disallow: /profile
Disallow: /searchresults
Disallow: /confirmation
Disallow: /wishlist_settings
Disallow: /wishlist
Disallow: /error
Sitemap: [Link]

Note: The XML sitemap is an index of page URLs on your store that is available for crawling
by search engines. It helps search engines to crawl your site more intelligently. Only pages,

8-15
 Chapter 8
Customize structured data

products, and collections that can be seen by anonymous shoppers (that is, visitors to
your store who are not logged in) are included in the generated sitemaps. Each
[Link] includes a <lastmod> tag that provides the date and time the item was
last published. See Understand XML sitemaps for more information.

Upload a custom [Link] file

The updateRobotsFile endpoint allows you to upload a custom [Link] file.

However in previous versions of Commerce, when publishing or on startup, the
RobotsManager automatically replaced this custom [Link] with an auto-
generated one. In this case it was advisable to contact support who were required to
manually disable automatic [Link] generation.

From the current version of Commerce, the updateRobotsFile endpoint automatically

disables the automatic [Link] file generation. Additionally, the new endpoint /
ccadmin/v1/merchant/seoConfig allows you to query, or update, the status of
automatic [Link] file generation.

Understand internal search results pages

Internal search refers to the search option on your own website when internal search
results pages are generated. To prevent creating low-quality pages, internal search
results are excluded from crawling in the [Link] file and are not found in Search
Engine Results Pages (SERPs).
Note: You can use Google Analytics to track internal search queries and use the
reports to regularly monitor for:
• the discovery of new keywords that customers use when searching for your
products.
• hints of navigational issues - users may be looking for existing categories that are
difficult to find in your main navigation.

Customize structured data

Commerce automatically generates a valid markup for the homepage, product, and
collection pages with: Products, Breadcrumbs, ItemLists, Reviews, WebSite, and
Organization properties.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The functionality to highlight page elements on certain template types and display in
Search Engine Results Pages (SERPs) is limited to Google only. Therefore, your
markup would not be seen by other search engines. Commerce enables you to switch
off the default markup for given page types, and substitute it with your custom script
template that utilizes values from Commerce variables.
JSON-LD is Google’s recommended implementation. When customizing your JSON-
LD, include as many applicable properties as possible to create different structured
data templates for different product types in your store.
You can use the Structured Data report in the Google Search Console to monitor how
Google interprets JSON-LD scripts across your store, and check for any markup errors
and warnings referring to missing properties. You can also verify how Google sees
structured data on a per page basis.

8-16
 Chapter 8
Understand XML sitemaps

Understand XML sitemaps

Commerce auto generates valid XML sitemaps for all of your store pages, or resource types.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Commerce resource types include:

• product
• category
• static pages
• video
• images
• supplementary pages: blog/lifestyle section

Determine page visibility settings

These settings will determine whether a URL appears in an XML sitemap:
• Active
This option hides a given page from the shopper. If a previously published product is
deactivated, you will be prompted to specify its redirect path. If you deactivate a category,
you are prompted to provide a direct path and warning displays indicating that you are
about to orphan your products. These will then be displayed in a separate folder for you
to assign to other active categories
• Meta robots directive
Commerce provides two options: index,follow (default) and noindex,follow. The latter
will exclude the page from Google search results, but crawlers will still follow and crawl
any links on that page.
• Canonical tag
This should be self-referential (default setting), or your custom URL.
• Exclude from Sitemap
This allows you to exclude specific pages from being included in XML sitemaps.
Your XML sitemaps should be submitted in Google Search Console and Bing Webmaster
tools. If your store’s static image assets are hosted externally/on subdomains then additional
hostnames should be verified in Search Console, and XML image sitemaps submitted for
those properties. Any possible crawling issues related to images can, therefore, be
monitored.
Note that sitemap URLs are generated automatically by Commerce for all of the locales that
correspond to a given site.

Work with the image XML sitemap

A separate XML image sitemap file utilizes both required and optional sitemap tags to
indicate to search engines which site images are to be crawled and indexed. By default, only
key body images, such as, product photos or homepage banners, are included in XML
sitemaps. Additional tags are utilized to include the image caption and title.

8-17
 Chapter 8
Understand SEO localization

Images are also included in the default structured data output in JSON-LD. Commerce
allows the customization of ALT and TITLE image attributes through editing single
images in the Media section, or bulk CSV upload. The default values for product
imagery include:
• ALT → product {displayName}
• TITLE → product {description} (short)
ALT and TITLE image attributes should be unique and not duplicates of product
display names or descriptions. It is recommended that you do not use too many
keywords or repeat the same attribute content. All product images should have
descriptive file names prior to being uploaded, and dashes should be used to separate
words, for example, [Link] should be used instead of
image_8974.jpg.

Note: You should avoid embedding copy into banners as this is illegible to web
crawlers. Instead, overlay text on top of imagery as only the ALT and TITLE attributes
can be interpreted. Also avoid using CSS background images and instead use
standard HTML <img src=””> to add imagery that you want to appear in search
results (namely all product photos on both product/collection pages). To add design
elements, such as, arrows, bars, small icons, and so on, you can use the CSS
background property.

Verify the XML sitemap

You can verify the validity of all your domains and subdomains in a search engine,
such as Google Search Console.
Submitting a valid XML sitemap file will influence how quickly your pages are crawled
and subsequently indexed. Google's Index Coverage report provides feedback on how
quickly new URLs are being processed. Note:You should allow some time for this
information to finalize as even though Googlebot may have seen your URLs, it does
not mean they will be automatically included in the index.
Sitemap submissions for larger sites enables you to verify the most important
directories of the main site as separate properties for easier monitoring. For multi-site
store directories, you can verify the language subdirectories as separate properties.

Understand SEO localization

Commerce platform auto generates hreflang tags that adhere to Google guidelines.
The hreflang tags enable search engines to serve the correct regional or language
URLs in search results based on the searcher's country and language preferences.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Plan your targeting

You are required to specify how many countries and language variants your site will
target. Consider how many translations you will be able to provide - you could target
20 countries, but you may only have to provide English, French, and German
language variants.
You will also need to decide on the number of country top level domains (cTLDs) your
site will incorporate under one Commerce panel. cTLDs such as .co, .uk, .ie., or .pt will
typically target their relevant country only, however, they are all perceived to be equal

8-18
 Chapter 8
Control access to storefront servers

by Google, so there is no disadvantage in terms of rankings to gain organic visibility with a

[Link] on [Link].
You may also choose to target multiple languages and locales from one gTLD only
(.com, .org, .net), for example, [Link]/en-gb/, [Link]/en-au. Your final
choice will also depend on the collection of domains already in use by your business.
When URL structures are planned out, country URL prefixes should not be used as they are
redundant. For example, [Link]/us-kitchen-accessories/or
[Link]/us-pottery/.

They do not contribute to the overall understanding of what a given page is about. If the same
domain is to target other languages/countries, subdirectories are recommended (rather than
subdomains).

Monitoring
Google Search Console allows to verify your language and locale targeting settings in the
Search Traffic, International Targeting report. The Language report can list up to 1,000 errors
with your hreflang implementation:

Note:For single language stores: if your domain is a generic TLD, you will be able to specify
your site-wide language setting.

Content localization
The purpose of multi-language stores is not only to translate the contents to cater to different
markets, but also to make content suited for the locales you wish to target. The process of
localization should go beyond translation only: accepting payments in local currency, adding
payment methods specific to a locale, adjusting delivery information for each geographical
location, using appropriate measurement systems. Also, you should always ensure that you
adjust any visual communications to suit different cultures accordingly.

Control access to storefront servers

In addition to the servers running your production storefront, you may have various other
storefront servers used for development, testing, and staging purposes.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

To prevent unwanted access to your storefront servers by web crawlers and other processes,
Commerce provides a basic authentication system. (This system does not apply to
administrative servers, as these servers already require OAuth 2.0 authentication to access
any content.) The basic authentication system checks various values associated with an
incoming request, such as the hostname, client IP address, and headers. If any of these
values is specifically allowed, the request is accepted without a challenge, but if not, a dialog
is displayed for entering a username and password. For example, your production server is
typically configured to bypass authentication if the request is sent to the official site URL
(such as [Link]), but the dialog is displayed if the request is sent to the internal
hostname (such as [Link]).

The primary purpose for the basic authentication system is not security, but rather to prevent
accessing the servers in an unexpected way. For example, if a web crawler accesses a test
server, the authentication system prevents it from indexing pages, so that web search results
do not direct shoppers to that server. On the production server, web crawlers are permitted to
index pages, but only when the pages are accessed via the official site URL.

8-19
 Chapter 8
Control access to storefront servers

Note that the basic authentication system is completely separate from any shopper
login. On your production server, shoppers should never see the authentication dialog
unless something is misconfigured.
Your servers are configured by default to display the authentication dialog only when
appropriate. You should typically not need to make any changes to the configuration.
However, the Admin API does include endpoints you can use to make changes to the
configuration, including the username and password, allowed headers, IP addresses,
and hostnames:
• To see your current settings, use the getBasicAuthConfiguration endpoint.
• To change your settings, use the updateBasicAuthConfiguration endpoint.
For more information about these endpoints, see the Oracle Commerce REST API
documentation in the Oracle Help Center:
[Link]

8-20
9
Manage Search Settings
The Search page in the administration interface contains a read-only table that lists all
properties that are searchable or serve as facets. You can use the Search page to configure
the searchable field rankings that determine how searches work in your store.
The Search page also lets you create synonyms for shoppers’ search terms in a thesaurus or
create keyword redirects for search terms. You can see the Search page only if you have
been assigned the Admin or Search role.
The topics in this section describe how to set up and manage search settings.

Understand index fields

A catalog property must be indexed before it can be considered when a shopper searches in
your store.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

To add a property to the index, select either or both of the following options in the property’s
configuration in the catalog:
• Allow property to be searched
• Allow property to be a search facet
After you publish this change, the property is added to the index, where it is represented by
an index field.
In order for a shopper’s search term to be matched against an index field’s contents, the field
must be configured as searchable in the catalog, (the first option previously described), and
must be added to the searchable field ranking list. Searchable field ranking changes take
effect after the next time you publish.

View index fields

The Index Fields page displays a read-only list of all the index fields for your site.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

To display the list, click Index Fields on the Search page. The list provides the following
information for each index field:
• Searchable
If this field is selected, shoppers can search on values entered for this property.
• Facet
If this field is selected shoppers can use this property as a refinement when filtering
search results.
• Multi-select

9-1
 Chapter 9
Understand the searchable field ranking list

If this field is selected, shoppers can use this property as a refinement and make
multiple selections to filter search results. For example, shoppers could filter
results by selecting several colors.

Understand the searchable field ranking list

Every place where a shopper uses search on your site is associated with a searchable
field ranking list.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The searchable field ranking list determines which records are returned in search
results – matches, and influences the order of these search results -- rank.
The searchable field ranking list is composed of an ordered list of fields:
• These fields are considered when a search term entered by a shopper is matched
against records.
• The order of these fields in the list affects the ranking of results.
You can view, add or delete fields from this list. Your site has at least two searchable
field ranking lists:
• All is the default searchable field ranking list for catalog searches.
• TypeAhead is a separate, auto-suggest searchable field ranking list.
For example, TypeAhead can return results in a type-ahead format when a shopper
types into a dropdown box.
Your site might have additional searchable field ranking lists for other types of
searches.
Note: In addition to the user interfaces described in this chapter, Commerce also
provides search Rest APIs that you can use to manage your searchable field ranking.
In the APIs, the searchable field ranking is known as a search interface. See Use the
REST APIs for more information.

Cross-field matching
Cross-field is the priority that is assigned to a matching record if the match is split
across multiple fields. A cross-field match can be configured to appear higher in the
results than some single-field matches.
Cross-field matching example
Consider two exact matches. One is product name + product color; the other match is
product description. The record that displays first depends on whether or not you use
and how you use cross-field matching.
A shopper enters “blue suede shoes” in the search box. Two records are matches, but
which one should have the higher priority? Here are the two records:

Record [Link] [Link] [Link]

One Suede shoes Blue Customer favorite

9-2
 Chapter 9
Add fields to the searchable field ranking list

Record [Link] [Link] [Link]

Two Suede shoes Red Tired of your blue
suede shoes? Try
these!

Record One is a match where “blue suede shoes” is split across multiple fields. Record Two
is a match where “blue suede shoes” occurs in a single [Link] field. Record
One is the better match and should have the higher priority, but it will only display first if the
following conditions are met:
• Your searchable field ranking list uses cross-field matching.
• Cross-field matches have a higher priority than a single [Link] field
match.
There are no rules for which fields in a searchable field ranking list should be given a higher
priority than cross-field matches, but you likely want to consider structured fields such as
category, brand, color, or features. Fields that allow more unstructured or free-form content,
such as a product description, should be given a lower priority and should display after cross-
field matches.
Cross-field matching is enabled by default for each searchable field ranking list. To disable
cross-field matching, you must use the search REST APIs.

Relevance Ranking
Search field ranking is taken into account by configurable modules that sort the records in
search results as part of a relevance ranking strategy. For information about how to configure
the sorting of search results, see Specify which index fields are included in searches.

Add fields to the searchable field ranking list

To make a field searchable, it must be configured as searchable in the catalog and be a
member of a searchable field ranking list.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Follow these steps to add a field to a searchable field ranking list.

1. Click the Search icon in the dashboard.
2. On the Search page, click Searchable Field Ranking.
3. Click the searchable field ranking list to which you want to add a field.
The searchable field ranking list displays index fields that are searchable. The order of
the fields in the searchable field ranking list affects the ranking of search results. Fields
higher up in the list have a greater ranking and search requests that match values in
these fields appear first in your search results.
4. Under Add Field, select the index field that you want to add to the searchable field
ranking list. You can also type the name of an index field in the box, and Commerce filters
the list to match what you have typed. The match is not case sensitive.
If you cannot find the field, you must find the associated property in the catalog, click
“Allow property to be searched,” and then publish your changes. See Create and edit
product types for more information. Note that it might be several minutes after publishing
completes for the new index field to appear.

9-3
 Chapter 9
Edit the searchable field ranking list

5. The field is added to the bottom of the list of index fields.

6. Click the field and then click and drag it to the position in the list that reflects its
rank.
7. Click Save.
Changes to the searchable field ranking list do not affect your store until after you
publish.

Configure cross-field matching

If cross-field matching is enabled for this searchable field ranking list, you can
configure where you want cross-field matches to display in a list of search results. To
learn more about cross-field matching, see Cross-field matching.
1. On the Search page, click Searchable Field Ranking.
2. Click the searchable field ranking list in which you want to configure cross-field
matching.
The searchable field ranking list displays a slider next to the list of index fields. If
the slider is disabled you cannot configure cross-field matching. To enable cross-
field matching, use the search REST APIs.
Moving the slider handle up or down changes where cross-field matches display in
your search results. Matches for index fields above the slider handle have a higher
priority. These matches appear before any cross-field matches. The index fields
below the slider handle have a lower priority than cross-field matches.
3. Move the slider handle up to give cross-field matches a higher priority, or down to
give them a lower priority.
4. Click Save.

Edit the searchable field ranking list

The order of the fields in the searchable field ranking list affects the ranking of search
results.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You can change the rank of index fields or remove them altogether from the
searchable field ranking list.
1. On the Search page, click Searchable Field Ranking.
2. Click the searchable field ranking list that you want to edit.
3. To change a field’s priority in search results, click the field and then click and drag
it to the position in the list that reflects the priority you want.
4. If you want to remove an index field so it is no longer considered for matches in
search results in this ranking, click the delete icon.
5. Click Save.
If you want to stop using a field for search in all searchable field ranking lists, you
can deselect “Allow property to be searched,” in the catalog and then publish your
changes. See Create and edit product types for more information. Commerce
recommends removing the index field from all searchable field ranking lists.

9-4
 Chapter 9
Understand the thesaurus

Understand the thesaurus

The thesaurus provides a way to include alternate terms for a shopper’s search query.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The thesaurus lets you create the synonyms that capture other ways of expressing queries
relevant to your store.
You can add two kinds of synonyms to your thesaurus:
• One-way thesaurus entries provide alternate ways of expressing query words or phrases
that apply in a single direction only.
For example, you could define a one-way mapping so that all queries for computer would
also return matches containing laptop, but queries for laptop would not return results for
the more general computer. You can add an unlimited number of synonyms to a one-way
entry, and Commerce expands the query to search for each synonym with the same one-
way relationship.
• Equivalent thesaurus entries establish a mutual equivalence relationship between words
or phrases. The words and phrases are interchangeable. A query for one term would also
return results for all other terms.
For example, an equivalent might specify that the phrase “notebook” is interchangeable
with the phrase “laptop.”
In the Rest API an equivalent thesaurus entry is known as a multi-way entry. See
Configure a thesaurus.
In addition to the user interfaces described in this section, Commerce also provides search
REST APIs that you can use to manage your thesaurus. See Configure a thesaurus for more
information.

Tips on using the thesaurus

The thesaurus can help customers find products in your store, but poorly conceived entries
might not be useful. To maximize the potential of the thesaurus, review the following tips:
• Do not create thesaurus entries for common spelling corrections. Commerce fixes
misspelled words automatically.
• Do not create equivalent entries with different cases of the same word. The thesaurus is
not case sensitive.
For example, entries such as Tartan = tartan are unnecessary.
• Do not create an equivalent entry for a word with multiple meanings.
For example, “khaki” can refer to a color as well as to a style of pants. If you create an
equivalent synonym for khaki = pants, then a shopper’s search for khaki towels could
return irrelevant results for pants.
• Do not create an equivalent synonym between a general and several more-specific
terms, such as top = shirt = sweater = vest. This increases the number of results the
shopper has to go through while reducing the overall accuracy of the items returned. In
this instance, if a shopper searches for “vest,” the shopper also gets results for “sweater.”
You get better results by creating individual one-way entries between the general term
“top” and each of the more-specific terms. In that case a search for vests would only
return vests, not sweaters, too. Only a search for “top” would return both sweaters and
vests.

9-5
 Chapter 9
Create and edit thesaurus entries

• Do not create an entry that includes a term that is a substring of another term in
the entry.
For example, consider an equivalent entry of “tackle” and “bait and tackle.” If
shoppers type “tackle,” they get results for “tackle” or “bait and tackle.” These are
the same results they would have received for “tackle” without the thesaurus. If
shoppers type “bait and tackle,” they get results for “bait and tackle” or “tackle,”
causing the “bait and” part of the query to be ignored.
• Avoid multiple word entries where single-word entries are appropriate.
In particular, avoid multiple word forms that are not phrases that shoppers are
likely to type, or to which phrase expansion is likely to provide relevant additional
results. For example, the equivalent entry “King Aethelbert of Wessex” = “King
Athelbert of Wessex” should be replaced with the single-word entry Aethelbert =
Athelbert.

Create and edit thesaurus entries

You create synonyms for shoppers’ search terms by adding them to the thesaurus,
which you access from the Search page in the administration interface.
You must be assigned the Admin or Search role to create or edit thesaurus entries.
Changes to the thesaurus do not affect your store until after you publish. See Publish
Changes.
You can see how your thesaurus entries behave when shoppers search for items by
previewing your store. Click Preview and then search for items that you expect to
trigger the thesaurus entries that you want to test. For more information about
previewing your store, see Preview your changes.

View the list of thesaurus entries

The thesaurus page displays a list of all the thesaurus entries that have been added to
your store. Each entry displays the following information:
• Search terms for one-way entries with an arrow that point to a list of synonyms.
Equivalent entries show synonyms only.
• The type of entry: one-way or equivalent.
• The last modified date, and the user that modified the entry.
The list can be sorted by clicking Sort By and selecting the type of entry, modified by
user, or date modified. Sorting always resets your view of the list to the first page. You
can filter the list by starting to type a search term, synonym, or user name in the Filter
list box.

Create one-way thesaurus entries

One-way thesaurus entries apply in a single direction only. When a shopper enters the
specified search term, the search results include the results for all of the synonyms for
the entry.
1. On the Search page, click Thesaurus.
2. Click New Entry.
The New Entry dialog displays with the default One-way option selected.
3. In the Search Term field, enter the word or phrase that a shopper might enter as a
query.

9-6
 Chapter 9
Create and edit thesaurus entries

4. In the Synonyms field, enter all the words or phrases to which a shopper’s search term
might map. The search results for the search term include the results for all the
synonyms. Press Enter or Tab between entries.
Note that the entries in this field do not map to one another or back to the term in the
Search Term field. If a shopper enters a term in the synonym list, the search results only
include the results for that term.
5. Click Create.

Create equivalent thesaurus entries

Equivalent thesaurus entries are mutually related words or phrases. When a shopper enters
any of the terms in a query, the search results include the results for all of the other synonym
terms.
1. On the Search page, click Thesaurus.
2. Click New Entry.
3. Click Equivalent.
4. In the Synonyms field, enter all the mutually related words or phrases that a shopper
might enter into a Search box. Press Enter or Tab between entries.
Note that the entries in this field are equivalent. This means that each of the entries in
this field produce the same search results when entered by a shopper. The entries are
interchangeable.
5. Click Create.

Edit an entry
You can edit an existing thesaurus entry as follows:
1. On the Search page, click Thesaurus.
2. Click the entry in the list.
3. If necessary, change the entry type.
If you change the entry from one-way to equivalent, the existing search term
automatically moves to the beginning of the synonyms list.
If you change the entry from equivalent to one-way, the existing synonyms remain intact,
and a blank Search Terms field appears.
4. Update a synonym by deleting it and re-entering it.
5. Click Save.

Delete an entry
To delete an entry from the thesaurus:
1. On the Search page, click Thesaurus.
2. Type a synonym or a search term for the entry that you want to delete into the Filter By
field.
3. Click the trash can icon next to the entry.
4. When the confirmation appears, click Delete.

9-7
 Chapter 9
Understand keyword redirects

Understand keyword redirects

You can configure a keyword redirect to send shoppers to a location in your store or an
external site when they enter a specified search term. This lets you display a relevant
promotional page or product category page instead of a typical list of search results.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

A keyword redirect is triggered by one or more search terms; the target of a keyword
redirect is a URL in your store or an external site. For example, a keyword redirect with
the search term “delivery” and the URL “[Link]
redirects shoppers to “[Link] if they use “delivery” as a
search term.

Site-specific keyword redirects

You can define a keyword redirect that applies to all sites or one or more specific sites
only. The same search term, entered on different sites, can redirect shoppers to
different pages. For example, if Site A and Site B have different policies for returns,
you can set up the term “returns” to take shoppers to different pages depending on the
site where they are shopping.
You can filter the list of keyword redirects by site to easily find all of the keyword
redirects defined for a specific site.

Match modes
The keyword redirect has three match modes. You can set the match mode to a non-
default setting by using the search REST APIs. See Configure the ranking of records
in search results for more information.
• Exact
Default match mode. A search query triggers a redirect only if the shopper’s
search query matches the keyword or a close variant exactly. The search query
cannot include additional words before or after the matching terms.
For example, if the keyword is “support” and the shopper enters “support,” then the
shopper is redirected. If the shopper enters “customer support,” then she is not
redirected.
• Phrase
A search query triggers a redirect if the terms in a shopper’s query match all the
terms in a keyword or a close variant in the same order. The search query might
include additional words before or after the matching terms.
For example, if the keyword is “customer support” and the shopper enters
“customer support telephone number” then the shopper is redirected. If the
shopper enters “support customer” or just “support,” she is not redirected.
• All
A search query triggers a redirect if the terms in a shopper’s query match all the
terms in a keyword or a close variant, but not necessarily in the same order.
The search query might include additional words before or after the matching
terms.

9-8
 Chapter 9
Create and edit keyword redirects

For example, if the keyword is “customer support” and the shopper enters “telephone
support customer number,” then the shopper is redirected. If the shopper enters
“telephone support number,” then she is not redirected.

Integration with the thesaurus

If you create a thesaurus entry that corresponds to a search term for a keyword redirect, the
keyword redirect has priority over the thesaurus entry.
For example, you might have a keyword redirecting “curtains” to [Link]
fallsale/curtains.

If you have a one-way thesaurus entry, with a search term of “curtains” and synonyms of
“drapes, shades” then the following occurs:
• A shopper who enters “curtains” as a search term is redirected to [Link]
fallsale/curtains.
• A shopper who enters “drapes” or “shades” as a search term is not redirected.
If you have an equivalent thesaurus entry, with synonyms of “curtains, drapes, shades” then
the following occurs:
• A shopper who enters “curtains” as a search term is redirected to [Link]
fallsale/curtains.
• A shopper who enters “drapes” or “shades” as a search term is not redirected.

Create and edit keyword redirects

You can create and edit keyword redirects for shoppers’ search terms on the Keyword
Redirects page.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Open the Keyword Redirects page from the Search page. You must be assigned the Admin
or Search role. Changes to the keyword redirects do not affect your store until after you
publish. See Publish Changes.
You can see how your keyword redirect entries behave when shoppers search for items by
previewing your store. Click Preview and then search for items that you expect to trigger the
keyword redirect entries that you want to test. For more information about previewing your
store, see Preview your changes.

View the list of keyword redirects

The Keyword Redirects page displays a list of keyword redirects that have been added to
your store. Each entry displays the following information:
• Keywords that the shopper enters.
• A redirect page which is the absolute or relative URL to which the shopper gets
redirected.
• A clickable icon that displays the redirect page in a new tab or window.
• The read-only match mode field.
• The last modified date, and user.

9-9
 Chapter 9
Create and edit keyword redirects

By default all keyword redirects are displayed. You can filter the list of keyword
redirects by site.
The list can be sorted by clicking the Sort By list and selecting keyword, redirect page,
modified by user order, or date modified order. Sorting always resets your view of the
list to the first page. You can filter the list by starting to type a keyword, redirect URL,
match mode, or user name in the Filter terms box.

Work with redirect URLs

Commerce recommends using relative URLs for redirecting shoppers to internal pages
within the store and only using absolute URLs for redirecting shoppers to external
pages outside of the store. Relative URLs are especially important for internal pages
because your preview storefront and production storefront have different hostnames.
Using relative URLs in this case allows you to preview and test your keyword redirects
before you publish.

Create a keyword redirect

All keyword redirects that you add using the administration interface have a match
mode of Exact.
1. On the Search page, click Keyword Redirects.
2. Check to see if the keyword has already been entered. If a keyword has multiple
entries with different redirect URLs, you might get unexpected results.
3. Click New Entry.
4. By default, the keyword redirect you create is global, that is, it applies to all sites.
To create a keyword redirect that applies to one or more specific sites, deselect
Global under Sites, click the Select items box and select the site or sites.
5. In the Keyword field, enter the term to be redirected to a page.
6. In the Redirect field, enter the absolute or relative URL for the page to which you
want the shopper to be redirected. The entry must begin with [Link] [Link]
or a forward slash (/).
7. Click Create.
8. Verify the redirect URL by clicking the redirect icon next to the URL.
The URL displays the redirect page in a new tab or window.

Edit a keyword redirect

You can modify the keywords or the redirect URLs for keyword redirect entries.
1. On the Search page, click Keyword Redirects.
2. Click the keyword entry in the list.
You can update an existing keyword or the redirect URL, or the site it applies to.
3. Click Save.
4. If you edited the redirect URL, verify it by clicking the redirect icon next to the URL.
The URL displays the redirect page in a new tab or window.

Delete a keyword redirect

1. On the Search page, click Keyword Redirects.
2. Click the trash can icon next to the entry.

9-10
 Chapter 9
Refine and order search results

3. When the confirmation appears, click Delete.

Refine and order search results

There are several ways to influence the ordering of the search results your shoppers see in
your store: specifying dynamic curation criteria, boosting and burying products, and using
facets.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Use dynamic curation

Dynamic curation allows you to influence the ordering of search results when the shopper
navigates to a category (collection) or enters a search term. With this feature, you can create
dynamic curation rules. Each rule has a destination (a collection or search terms), a set of
criteria for ordering the search results, and an importance level for each criterion. Search
uses your prioritization and blends the criteria to generate a sort order.
For example, in collections within Women’s, you can prioritize products that are newest,
bestselling, and in stock; whereas within Men’s, you can prioritize bestselling, in stock, and
most viewed. As another example, you can display in-stock and on-sale items near the top of
the search results.
The dynamic curation feature does not replace the configuring Searchable Field Ranking
feature, but rather supplements it. For text searches, it is best to configure Searchable Field
Ranking to return the most relevant results first, and use dynamic curation rules sparingly.
Otherwise, you might not display the most relevant results consistently.
You cannot test views and sales in Dynamic Curation in your staging or test environment.
Dynamic curation rules apply to all search-driven pages (where another dynamic curation rule
does not apply), and not to collection pages driven by the repository. For example:
• If your storefront is customized such that the category pages accessed from the top-level
collections are search-driven, the curated ordering applies on those pages.
• If the shopper uses guided navigation to navigate to a category page, the curated
ordering applies on that page.
• If your storefront is not customized, the collection pages accessed from the top-level
collections are repository-driven, and dynamic curation rules do not apply to them.
In addition, with the default search settings in Commerce, consider the following:
• When a curation rule has search terms as a destination, the rule serves only as a
tiebreaker - that is, it takes effect only when two or more products that have the same
relevance need to be ordered.
• When a curation rule has a collection as a destination, the criteria in the rule have a more
direct effect, since relevance is not a consideration in the ordering. A rule defined for a
collection applies to all sub-collections, except for any sub-collections that have their own
rules.
Also be aware that because the underlying algorithm blends the criteria, predicting the search
results order exactly may not always be possible.

9-11
 Chapter 9
Refine and order search results

Implement dynamic curation

This section describes how you can use the dynamic curation feature to influence the
ordering of search results. Any changes you make will take effect in production after
you publish them.
Create a curation rule
Follow these steps to create a new curation rule:
1. On the Search page, click Dynamic Curation.
2. Click New Curation Rule.
3. Select the site the rule applies to.
4. Select a collection or enter one or more search terms to define which search
results will be ordered.
5. Click Add Criteria to select the criteria.
Note: If you choose Newness as a criterion, it will only apply to products that are
less than 100 days old. In addition, if Arrival Date is not populated for a product,
Creation Date will be used instead.
Note: The In Stock criterion only uses the default inventory; location-level
inventories are not supported.
6. Use sliders to rate the importance of each criterion you have selected.
7. If you selected Product type, select and order the product types.
8. Click Create.
Update a curation rule
Follow these steps to edit an existing curation rule:
1. On the Search page, click Dynamic Curation.
2. Click on the curation rule you want to edit from the list of dynamic curation rules.
3. Update the collection or search terms to define which search results will be
ordered.
4. Click Edit Criteria.
5. Use sliders to rate the importance of each criterion you have selected.
6. Click Save.
7. Optionally click Save and Preview to preview the search results you just curated.
For site-specific rules, click the preview button on the header of the administration
interface.
Delete a curation rule
Follow these instructions to delete a curation rule:
Note: The default rule cannot be deleted.
1. On the Search page, click Dynamic Curation.
2. Click on the curation rule you want to delete from the list of dynamic curation rules.
3. Click Delete.
4. When the confirmation appears, click Delete.

9-12
 Chapter 9
Refine and order search results

Boost and bury products

In addition to specifying the dynamic curation criteria, you can promote (boost) products to
the top of the search results and move products to the bottom of the search results (bury).
Follow these instructions to boost or bury products:
1. On the Search page, click New Curation Rule.
2. Select the site the rule applies to.
3. Select a collection or enter one or more search terms to define which search results will
be ordered.
4. Click Add Products under Select products to boost or Select products to bury to
search for, select, and add products to be boosted or buried, respectively. In the grid of
boosted or buried products, you can reorder products using drag and drop or the context
menus. Alternatively, switch to the list view to edit the products' sequence numbers.
5. Click Create.
6. Optionally click Create and Preview to preview the search results you just curated. For
site-specific rules, click the preview button on the header of the administration interface.
Note: You can boost a maximum of 200 products and bury a maximum of 200 products.

Order facets
You can select and order the facets that appear in the Guided Navigation widget when the
shopper views search results or navigates to a search-driven collection.
• You can specify the default facets. These facets appear in the Guided Navigation widget
on any search-driven page that does not have its own explicitly defined list of facets.
• You can create an ordered list of facets for a specific collection. These facets appear in
the Guided Navigation widget when the shopper views the collection’s search-driven
page.
• You can create an ordered list of facets for one or more search terms. These facets
appear in the Guided Navigation widget when the shopper enters any of the search
terms.
Follow these instructions to add facets:
1. On the Search page, click Facet Ordering and then New Facet Ordering Rule.
2. Select the site the rule applies to.
3. Select a collection or enter one or more search terms to define which search results
whose facets you want to order.
4. Click the Add facet field to add facets.
5. Click Create and then Save.

Understand the behavior when a collection is created in two catalogs

If you create a collection in two catalogs on the same site, with the same path in each
catalog, the collection will appear once in Dynamic Curation and Facet Ordering, under the
site’s default catalog. A rule created for this collection will apply in both catalogs.
If you create a collection in two catalogs on different sites, or in two catalogs on the same
site, but with a different path in each catalog, the two collections will both appear in the

9-13
 Chapter 9
Multiple sites and search

collection picker in Dynamic Curation and Facet Ordering. If you want the same rule to
apply to both collections, you must create the rule twice, once for each collection.

Multiple sites and search

If you run multiple sites within a single instance of Commerce, these sites share a
single search configuration.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Your sites share the following search features:

• All searchable field ranking lists
• A single thesaurus

Configure dynamic content

With Dynamic Content, merchandisers can return dynamic content alongside products
and navigation.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

For one or more search terms, or for any collection, you can choose dynamic media
from the media library. When a shopper enters one of the search terms, or navigates
to the collection, the metadata for the image along with the search results are
returned. For example, a search containing the term "sale" may display a clickable
banner with "Click here to go to our sale page".
Open the Dynamic Content page from the Search page. You must be assigned the
Admin or Search role. Changes to the dynamic content do not affect your store until
after you publish.
You can see how your dynamic content rules behave when shoppers search for terms
or view a collection by previewing your store by clicking Save and Preview. If a widget
has been created and placed on the Search Results or Collection layout, you can see
the destination and that the image you specified is displayed.

Create a dynamic content rule

Follow these steps to create a new dynamic content rule:
1. On the Search page, click Dynamic Content.
2. Click New Content Rule.
3. Select the site the rule applies to.
4. Select a collection or enter one or more search terms to define the search results
where you want to spotlight your content. Or you can select All destinations on
the selected sites.
5. Click Select Media to select or add an image to display. Multiple image selection
is not supported.
6. Optionally enter URL information in the Link URL field. A shopper who clicks on
the image will be taken to this URL.

9-14
 Chapter 9
Configure dynamic content

7. Click Create.

Update a dynamic content rule

Follow these steps to edit an existing dynamic content rule:
1. On the Search page, click Dynamic Content.
2. Click to open the dynamic content rule you want to edit from the list of dynamic content
rules.
3. Update the site, destination or media.
4. Click Save.
5. Optionally click Save and Preview to preview the search results. For site-specific rules,
click the preview button on the header of the administration interface.

Delete a dynamic content rule

Follow these steps to delete a dynamic content rule:
1. On the Search page, click Dynamic Content.
2. Click to open the dynamic content rule you want to delete from the list of dynamic content
rules.
3. Click Delete.
4. When the confirmation appears, click Delete.

Create dynamic content widgets

To display dynamic content, you create a dynamicContentList widget. The widget can be
added to the Search Results layout or the Collection layout of Storefront or Agent. The widget
also ensures that a shopper who clicks on the image is redirected to the URL specified in the
rule.
In the search response, the dynamic content is returned in the additional content property
and this is mapped to the additional content property in the searchResultsDetails view
model. The widget instances interact with the view model to retrieve and display the image.
A dynamicContentList widget could be created in a way similar to the following example,
which you could store in a file named [Link]:

define(
['jquery', 'knockout', 'ccLogger', 'pubsub'],
function($, ko, CCLogger, pubsub) {
'use strict';
return {

onLoad : function(widget) {
[Link] = [Link]();
[Link] = function(result) {
if([Link] && [Link] &&
[Link]>0){
[Link]([Link]);
} else {
[Link]([]);
}

9-15
 Chapter 9
Use the search REST APIs

};
$.Topic([Link].SEARCH_RESULTS_UPDATED).subscribe(widge
[Link]);
$.Topic([Link].SEARCH_RESULTS_FOR_CATEGORY_UPDATED).su
bscribe([Link]);
}
}
}
);

Once you have retrieved the dynamic content image URL, you can display it using
your widget template. The [Link] file might contain the following:

<div id="cc-dynamic-content">
<!-- ko if: dynamicContentList().length > 0 -->
<h3> Displaying dynamic content </h3>
<!-- ko foreach: dynamicContentList-->
<!-- ko if: $data['@type'] == "Media" -->
<div id="banner" >
<a data-bind="attr:{href: $data['linkURL']}">
<img class="img-responsive center-block" data-bind="ccResizeImage: {
isSrcSetEnabled : true,
source: $data['imageUrl'] }"/>
</a>
<br/>
</div>
<!-- /ko -->
<!-- /ko -->
<!-- /ko -->
</div>

Use the search REST APIs

Some search-related tasks cannot be done through the administration interface and
can only be completed using the search REST APIs.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The following tasks must be completed through the REST APIs:

• Create and delete a searchable field ranking list
• Enable and disable cross-field matching
• Enable different types of partial matching
• Specify snippet sizes
• Select modules that sort search results as part of a relevance ranking strategy
• Configure locales, search term wildcards, and spelling dictionaries
See Use the REST APIs for more information.

9-16
10
Manage Media for Your Store
You can upload and manage product and collection images, as well as media that you use in
other places on your store, such as a hero image on the home page. Commerce
automatically sizes your images for display on different devices, such as laptops, tablets, and
mobile phones.
This section describes how to use the Media tab to upload and manage images that appear
on your store.

View the media library

Click the Media icon to see all the files in your media library displayed in a grid.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Media files are initially sorted by name, though you can also sort them by size or last-
modified date. You can also display them in a list.
The media library stores files in the following folders:
• Products - contains media files assigned to and available to products.
• Collections - contains media files assigned to and available to collections.
• General contains media files you can access when you configure the design elements for
your store. See Design Your Store Layout for more information.
Click Products, Collections, or General to view and access just that folder’s media files and
to upload the selected types of files. Click All Media to view and access all files in your media
library. You cannot move media files from one folder to another.
Click an image to display details for that file, including name, path, size, file type, and the
date and time it was last modified.
There is a unique URL for each published item in your media library, providing a direct link
that lets you open the item in a browser. Format the URL as follows:
<[Link]>/file/<path>

• <[Link]> is the URL Oracle provides to access your store.

• <path> is the value of the Path field, which you can see when you click the image on the
Media page.
For example, suppose the file [Link] contains a warranty for a TV sold on your
store [Link]. The file is stored in the General folder. Use the following URL to
access the PDF:
[Link]/file/general/[Link]

10-1
 Chapter 10
Upload media files

Upload media files

You can upload individual files to the media library or you can compress media files in
a ZIP file, which you then upload to Commerce.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You can name media files so they are automatically assigned to products or collections
in your catalog.
This section includes the following topics:
• Automatically assign images to products and collections
• Upload individual images
• Upload multiple media files

Automatically assign images to products and collections

You can format image-file names so that they are automatically are assigned to
products and collections in your catalog when you upload them.
Format file names for product and collection images as follows:
<product_id>.<name>.<file_type>
<collection_id>.<name>.file_type>

• <product_id> is the product’s Product ID property. See Create and work with
products for more information.
• <collection_id> is the collection’s Collection ID property. See Create collections
for more information.
• <name> is the descriptive name portion of the file.
• <file_type> is the file extension. Only JPG/JPEG, PNG, and GIF files can be
automatically assigned to products and collections.
For example, suppose you want to assign several images to a pair of boots whose
product ID is xprod2102. You could upload the following files:

[Link]
[Link]
[Link]

Keep the following in mind when you name media files to upload:
• A file cannot be assigned to a product or collection if a file of the same name is
already assigned to it.
• The file name is case-sensitive. For example, the system considers
[Link] and [Link] to be two
different files.
Product IDs are case sensitive. xprod030 and XPROD030 are different product IDs.

10-2
 Chapter 10
Edit and remove media files

You can also import assignments in bulk for images that you have already uploaded. See
Import image assignments for more information.

Upload individual images

You can upload individual JPG/JPEG, PNG, and GIF files to the media library. You can name
media files so they are automatically assigned to products or collections in your catalog once
they are uploaded. See Automatically assign images to products and collections for more
information.
To upload a single image:
1. On the Media page, select the type of media files to upload. Select Products,
Collections, or General.
2. Click Upload.
3. Select an image to upload.
You can upload only one image at a time. To upload multiple images at once, see Upload
multiple media files.
If you select a file with the same name as a file you already uploaded, the new file
replaces the existing one.
4. Click Save.

Upload multiple media files

To upload a number of media files at once, compress them in a ZIP file, then upload the ZIP
file to the media library. Commerce scans the ZIP file for viruses and checks to ensure it
contains only allowed file types. (You can upload only GIF, JPG/JPEG, PNG, SWF, SVG, and
PDF files.) You can name media files so they are automatically assigned to products or
collections in your catalog once they are uploaded. See Automatically assign images to
products and collections for more information.
Note: Each ZIP file cannot be larger than 1GB. If your upload times out, check the ZIP file to
make sure its size is 1GB or smaller.
To upload the ZIP file:
1. On the Media page, select the type of media files to upload. Select Products,
Collections, or General.
2. Click Upload.
3. Find the ZIP file to upload and click Open.
Depending on the size of the ZIP file, this process could take some time to complete.
Remember that the ZIP file you upload must not be larger than 1GB.
When the upload is complete, the Upload Media dialog displays the total number of new
and changed files, errors, and files assigned to products or collections. To see a complete
report for the upload in CSV format, click Download Full Report.
If you upload a file with the same name as a file you already uploaded, the new file
replaces the existing one.

Edit and remove media files

You can change a media file’s name or remove it from the media library.

10-3
 Chapter 10
Import image assignments

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This section includes the following topics:

• Rename media files
• Remove media files

Rename media files

You can rename a file in the media library. If the file is an image assigned to a product
or collection, renaming it breaks the connection to the product or collection. Once you
save the new name, however, the service checks the name and if the name is
formatted correctly, automatically assigns the image. See Automatically assign images
to products and collections for more information.
To rename a media file:
1. On the Media page, find the file you want to rename and click.
2. Enter a new name in the Name box.
Do not use the same name as an existing file in the same folder.
3. Click Save.

Remove media files

When you remove a file from the media library, you cannot access it again with the
Commerce tools. If you remove the primary image for a product or collection, the next
image assigned to it becomes the primary image. If you remove all images from a
product, a placeholder is displayed on your store.
To remove a file from the media library:
1. On the Media page, navigate to the files you want to remove.
2. Hover over a file and click the X icon when it appears.
To remove multiple files, hover over a file and click the check mark icon when it
appears. (To remove all the files on the current page, click Select All.) Repeat this
for all the files you want to remove and then click the X icon on any of them.
3. Confirm that you want to remove the selected files.

Import image assignments

You can use the Oracle Commerce import process to assign a number of already-
uploaded images to products and collections at once and to create a title and alt text
for each assigned image.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

See Import and Export Catalog Items and Inventory for details about how to import
and export data in Oracle Commerce.
The easiest way to format a file for importing image assignments for products or
collections is to start by exporting a file that you can use as a template for the items
you want to add or modify. See Export catalog items for more information about how to
export.

10-4
 Chapter 10
Import image assignments

When you look at the exported spreadsheet, you can see that the second row displays
column headings that contain the internal names of the exported properties. There are three
properties for image assignment:
• images specifies the name and path of the uploaded image to assign to the product or
collection)
• altText specifies the alt text to assign to the image.
• title specifies the title to assign to the image.
Product or collection data begins in the third row and continues for the remainder of the
spreadsheet. If an item does not have a value for a property, the corresponding cell is blank.
When you enter data in the images column, you must format it as follows:
media<number>:<path>/<file_name>

• <number> is the number that specifies the display order of the image. media1 specifies
that the file will be displayed as the primary image.
• <path>/<file_name> specifies the full path to the image and the name of the image file,
including the extension. The path and file name for an image is shown in the Path field on
its details page, which you access from the Media page. See View the media library for
more information.
Note: When you import multiple image assignments for a product or collection, you separate
them with a | (vertical bar). Therefore, you should not use this character in any media file
names.
See Import catalog items and inventory for more information about how to import your
changes back into the catalog.

10-5
11
Import and Export Catalog Items and
Inventory
You can export products, SKUs, collections, and catalogs to a file in CSV (Comma Separated
Value) format so you can work with them outside of Oracle Commerce and easily import
changes back into your Commerce environment.
The following are examples of changes you can make by exporting and importing data:
• If you are a new Commerce customer, you can import an existing catalog to initially
populate your storefront.
• If new catalog information arrives on an automated feed, you can format and edit the new
assets in bulk and import them into your catalog.
• If you receive updates from a number of people, you can incorporate all the changes into
your catalog at once instead of manually entering each change.
• You can quickly make bulk edits or perform global operations (like search and replace or
spell-checking) on catalog assets in a spreadsheet and then import those changes back
into your catalog.
• You can distribute asset information for review to people who do not have access to the
Commerce tools.
• If you let shoppers view your store in different languages, you can import translations for
each language your store supports.
You can also import inventory data, such as inventory count and stock threshold, for products
and SKUs into your catalog.

Understand export guidelines

It is important to plan before exporting your data.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This section provides information that helps you plan and understand your export.
• You can export products, SKUs, collections, and catalogs.
• You can export only one type of item in each export procedure. For example, you cannot
export both products and collections to the same spreadsheet; you must export the
products in one export procedure and then export the collections in another.
• Exporting catalogs exports properties that describe each of your catalogs, such as ID,
display name, and root categories. Exporting catalogs does not export the products,
SKUs, and collections the catalogs include.
• When you export products, SKUs, collections, and catalogs, all available properties are
automatically exported. You cannot change the list of properties to export.

11-1
 Chapter 11
Export catalog items

• If you modified a product, SKU, collection, or catalog, the modified version is

exported, even if you have not published the changes. For items you have not
modified, the published version is exported.
• If your Commerce instance uses multiple catalogs, you can export products,
SKUs, and collections from a specific catalog or from all catalogs. You can also
export items in Unassigned Products and Unassigned Collections, which are not
associated with any catalogs.

Export catalog items

You can export products, SKUs, collections, and catalogs to a file in CSV (Comma
Separated Value) format so you can work with them outside of Commerce and easily
import changes back into your Commerce environment.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This section includes the following topics:

• Export products, SKUs, and collections
• Export catalogs
• Specify export filter criteria
• View the exported data

Export products, SKUs, and collections

Follow these steps to export products, SKUs, or collections to a spreadsheet:
1. On the Catalog page, click the Export button.
2. Select the items to export: Products, Product Variants (SKUs), or Collections.
3. If your Commerce instance includes multiple catalogs, specify which catalogs to
export from: Select All Catalogs to export the selected items from all catalogs.
This is the default selection.
4. If your store supports more than one language, select the language to export from
the Language list. This list does not appear if your store supports only one
language.
5. If you want to export a subset of items, select Filter Items Being Exported See
Specify export filter criteria for more information.
6. Click Export.
Once you click the Export button, the operation cannot be canceled and you
cannot work on other tasks until the export is complete.
7. When the export is complete, your browser displays a dialog box where you
choose whether to open or save the spreadsheet.
If you click Cancel in this dialog box, the export file is not saved and you must
repeat the export procedure.
8. See View the Exported data for information about how to understand the exported
data.

Export catalogs
Follow these steps to export information about all catalogs to a spreadsheet:

11-2
 Chapter 11
Export catalog items

1. On the Catalog page, click the Export button.

2. Select Catalogs from the list of items to export.
3. If you want to export a subset of items, select Filter Items Being Exported See Specify
export filter criteria for more information.
4. Click Export.
Once you click the Export button, the operation cannot be canceled and you cannot work
on other tasks until the export is complete.
5. When the export is complete, your browser displays a dialog box where you choose
whether to open or save the spreadsheet.
If you click Cancel in this dialog box, the export file is not saved and you must repeat the
export procedure.
6. Read View the Exported data for information about how to understand the exported data.

Specify export filter criteria

By default, when you export products, SKUs, collections, and catalogs, Commerce exports all
of the type of item you selected. To export fewer items, you can create rules that filter the
items based on properties you specify, such as a parent collection for products.
Note: You cannot save filter rules. If you select a different type of item to export or navigate
away from the Catalog page, any filter rules you created will not persist when you return.
To create a rule while exporting items, follow these steps:
1. In the Export Catalog dialog, select Filter Items Being Exported.
The operators you see depend on the type of property you selected.
2. If you selected a specific catalog to export from and that catalog has filtered views, you
can select one from the Select Filtered View list. The default selection is All Filtered
Views.
3. Click Add Rule.
4. Select a property from the drop-down list in the rule. The available properties depend on
the type of items you are exporting. You can select only one property per rule.
5. Select an operator that links the property to a value that you will specify in the next step.
The operators you see depend on the type of property you selected.
6. Select or enter a value for the property.
For some values, such as Parent Collections, Commerce displays a list for you to choose
from. For others, such as Name or ID, you must type in a value. The rule editor does not
validate any text, numeric, or date values you enter.
7. If you create more than one rule, select one of the following options from the Match list to
specify how the rules behave together. You can select only one option for the entire set of
rules.
• Any: If an item matches any rule in the set, it is exported.
• All: (default) If an item matches all the rules in the set, it is exported
8. Click Export.

View the exported data

The exported CSV file can be viewed and edited using a spreadsheet program such as
Microsoft Excel. The default file name follows the format <YYMMDDhhmmss>[Link].

11-3
 Chapter 11
Export catalog items

For example, a file exported January 30, 2017 at 11:43:27 AM is named

[Link].

The exported data follows a specific format that can be used to re-import the
spreadsheet to Commerce. The following figure shows an example of exported
product data in a spreadsheet:

Row One: Repository, Item Type, Formatting Options, and Process Messages
The first row is reserved for the repository path and item type, any formatting options,
and any warning or error messages.
• The first column of row one (cell A1) contains the repository path and the item type
separated by a colon. For example: /atg/commerce/catalog/
ProductCatalog:product
• Columns two through six (cells B1, C1, D1, E1, and F1) contain data formatting
options:
TIMEFORMAT appears in the third column (cell C1) and shows the format used for dates
with a time stamp, for example, TIMEFORMAT=MM/dd/yyyy HH:mm:ss.

If your store supports more than one language and you selected a different export
language than the default language for your store, LOCALE appears in the fifth column
(cell E1) and shows the ISO locale format for the language, for example, en_US.
If your Commerce instance includes multiple catalogs and you selected a specific
catalog to export from,CATALOG appears in the sixth column (cell F1) and shows the
catalog ID, for example, CATALOG=movieCatalog.
Row Two: Property Headings
The second row displays column headings that contain the property names of the
exported properties. The ID property is always the first column (cell A2) and is always
labeled “ID” regardless of the actual repository name of the ID property.
Note: The spreadsheet contains the Property ID and Label of the property and not the
localized display name.
Rows Three and Greater: Data
Catalog data begins in the third row and continues for the remainder of the
spreadsheet. If an item does not have a value for a property, the corresponding cell is
blank.
Data for filtered catalogs
When you export products or SKUs and your Commerce instance contains filtered
catalogs, the second row of the exported spreadsheet includes column headings that
contain the following property IDs:
• The coreProduct column specifies whether the item is a core product in the
catalog.
• The filteredCatalogs column includes the Catalog IDs that specify filtered
catalog the item belongs to.

11-4
 Chapter 11
Import catalog items and inventory

See Work with filtered catalogs for more information.

Data for exported catalogs
When you export catalogs, the second row of the exported spreadsheet always displays
column headings that contain the following internal property IDs.
• The ID column includes the Catalog ID for each catalog.
• The displayName column includes the Catalog Name for each catalog.
• The catalogVersion column includes an integer that specifies the type of catalog. 1
specifies a legacy catalog, 2 specifies an independent catalog, and 3 specifies a filtered
catalog. See Understand catalogs for more information.
Note: You cannot change a catalog’s catalogVersion value if you import the file back
into Commerce. If you do, the import will fail.
• The rootCategories column includes a comma-separated list of Collection IDs for the
collections in each legacy catalog.
This column contains values only for catalogs whose catalogVersion value is 1.
• The rootNavigableCategory column includes the navigable root collection for each
catalog whose catalogVersion value is 2. The default value for this property is
rootCategory.
• The rootNonNavigableCategory column includes the non-navigable root collection for
each for each catalog whose catalogVersion value is 2. The default value for this
property is nonNavigableCategory.
• The defaultCategoryForProducts column includes the Collection ID of the collection
that will automatically be the parent of any product created or imported in this catalog
without a specified parent.
This column contains values only for catalogs whose catalogVersion value is 2.

Import catalog items and inventory

The import feature lets you work with products, SKUs, collections, and catalogs outside of
Commerce and import them, in spreadsheet format, back into Commerce.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Importing provides a convenient method for adding items and batch editing.
You can also import inventory data for products and SKUs into your catalog. Importing
inventory is a separate procedure from importing products, SKUs, collections, and catalogs.
The following procedure is an overview of the steps you perform to import either catalog
items or inventory from a spreadsheet into Commerce:
1. Create a spreadsheet in the correct format for importing to Commerce. For more
information see Export catalog items and Format a file for import.
2. Load the file and validate that the items can be imported.
3. Import the spreadsheet. For more information, see Import products, SKUs, collections, or
catalogs.
4. Review the outcome of the import for any errors or warnings. For more information, see
Validate and preview items.

11-5
 Chapter 11
Import catalog items and inventory

5. Review the imported items on the Catalog page.

Format a file for import

The easiest way to format a file for importing products, SKUs, collections, or catalogs
is to start by exporting a file from your catalog that contains the items you want to
modify. If you are importing inventory, you must manually create the import file starting
with a blank spreadsheet.
Caution: If you leave a cell blank, a property value might be deleted. See instructions
later in this section for marking data to ignore.
Required formats for importing a spreadsheet
The first row and first column of the spreadsheet are reserved for use by the import
process and must contain specific information. The first row contains information about
the data that is being imported and the first column (except for row 1) contains the ID
property of the items being imported.
In the first row of the spreadsheet, you must specify the repository, item type, and any
special formats for data types, as follows:
• For catalog items: The first column of row one (cell A1) must contain the internal
component path and should be left exactly as exported when you created the
import template. For example, the following path indicates that the spreadsheet
contains products:
/atg/commerce/catalog/ProductCatalog:product
• For inventory: Cell A1 must contain the following path:
atg/commerce/inventory/InventoryRepository:inventory
• Use the additional columns in row one (cells B1 through D1) to specify any special
property formatting, such specific date formats. Each format must be in its own
cell, but it does not have to appear in any particular order. The following table
describes the formatting options:

Description Format in Spreadsheet Requirements

Format of date property DATEFORMAT=MM/dd/yyyy Required if any imported
values, such as 01/31/2009 The day, month, and year properties are of type date.
indicators can appear in any The date value must exactly
order to match your data, for match the format, for example
example dd/MM/yyyy 03/15/2014 instead of 3/15/14.
Format of timestamp property TIMEFORMAT= Required if any imported
values, such as 31/01/2009 MM/dd/yyyy HH:mm:ss properties are of type
22:45:01 timestamp.
The day, month, and year
indicators can appear in any The timestamp value must
order to match your data, for exactly match the format, for
example, dd/MM/yyyy example 03/15/2014 05:30:00
HH:mm:ss instead of 3/15/14 5:30.
To use 12-hour time, the
format is MM/dd/yyyy
hh:mm:ss aa, where aa can
be either AM or PM, for
example 03/15/2009 05:30:00
AM

11-6
 Chapter 11
Import catalog items and inventory

Description Format in Spreadsheet Requirements

ISO locale format of the LOCALE=locale Required if you are importing
language you are importing. The ISO locale format for the translations for a particular
See Localize Your Store for language, for example, language.
more information about en_US.
importing translations.
ProductCatalog:sku LOCALE=locale The ISO locale format for the
ID=SKU language, for example,
en_US.
displayName=
Qualified SKU
parentProduct=
Text name
Type=
Parent product, if any.
configurable=TRUE/FALSE
An empty string or a valid type
productLine=
that is defined in the
productFamily= repository.
barcode= TRUE/FALSE
active=TRUE/FALSE Product Line, if any.
nonreturnable=TRUE/FALSE Product Family, if any.
bundledSkusItem=item1:Sku_ Qualified barcode
5Cxy|item2:Sku_27Gxyzii
TRUE/FALSE
bundledSkusQuantity=item1:2|
TRUE/FALSE
item2:1
SKUs in the bundle.
configurationMetadataName=
Quantity of each SKU in
configurationMetadataValue=
bundledSkusItem
Meta data name, if any.
Value for
configurationMetadataName

Beginning with the second row, the first column of the spreadsheet is reserved for the ID
property of the imported items. No other property can occupy column one.
• For catalog items: The second row (cell A2) contains the ID heading, which is always ID
regardless of the actual name of the repository item’s ID property. The remaining rows
(cells A3 and greater) contain the ID values for each imported item. Any rows with blank
ID values are skipped during import.
• For inventory: The second row (cell A2) contains the ID heading, which is always
catalogRefId regardless of the actual name of the repository item’s ID property. Cell B2
contains the label stockLevel. Cell C2 contains the label stockThreshold. Cell D2
contains the label preorderLevel. Cell E2 contains the label preorderThreshold. Cell F2
contains the label backorderLevel. Cell G2 contains the label backorderThreshold. Cell
H2 contains the label availabilityDate.
Keep in mind that ID values can contain only alphanumeric characters, hyphens (-), and
underscores (_).
For details about preorder and backorder levels and thresholds, see Manage Inventory for
Preorders and Backorders.
Import file size limitations
The maximum number of item rows that can be imported from a single spreadsheet is
25,000. If you import more than 25,000 items, any items above that limit are not imported and
the import report includes a message that tells you the import was truncated.

11-7
 Chapter 11
Import catalog items and inventory

Format for importing non-ASCII characters

When you import text properties (such as display names for products, SKUs, and
collections) that contain non-ASCII characters, you must save the CSV file with UTF-8
encoding before you import it. Otherwise, the non-ASCII characters will appear
garbled in the administrative interface.
Note: When you export text properties that contain non-ASCII characters, those
characters do not automatically display in the exported CSV file. In order to display
these characters in the CSV file you must save it with UTF-8 encoding
Format for importing custom-property values
If your spreadsheet includes values for custom properties, it must include a column
with the heading type in the second row. For each row that includes a value for a
custom property, this column must include the ID of the product type that contains the
property.
Format for adding new items
The import feature allows you to create new items when you import your spreadsheet.
To create an item, add a row to the spreadsheet and enter property values for each
column. If you leave a cell blank, then the value for that property is set to null. If you
leave the ID column blank, the item is skipped and not created.
Creating new items is supported only for importing products, SKUs, and collections. It
is not supported for importing inventory.
You assign an ID value for the new item in one of the following ways:
• Enter NEW in the ID column to let Commerce create an ID.
The new item is created using an automatically generated ID. The NEW keyword
must be typed in all capital letters and must be the only value in the cell.
• Enter a unique ID in the ID column.
A new item is created with the ID you enter.
To create a new top-level collection, in addition to adding the new row, you must also
add the new collection’s ID to the fixedChildCategories column of the rootCategory
row. For example, if you add a row to the spreadsheet to add a new category whose
ID is cat5000, you must also add the ID cat5000 to the fixedChildCategories column
of the rootCategory. Otherwise, the new collection will not appear in the Catalog tree
in the administration interface.
Note: To create an item, you must provide values for required properties.
Format for adding new items to specific catalogs
You can use import to create new products, SKUs, and collections in specific
independent (version 2) catalogs. (By default, products, SKUs, and collections are
imported into the main Product Catalog that is included with Commerce.) See Work
with independent catalogs for more information.
In order to create new items in specific catalogs, you must enable support for the
feature. To do this, you issue a PUT command to the adminConfiguration endpoint in
the Admin API to set the value of the useCatalogHeaderForCreatingNewItems
property to true. For example:

PUT /ccadmin/v1/merchant/adminConfiguration HTTP/1.1

Authorization: Bearer <access_token>

11-8
 Chapter 11
Import catalog items and inventory

Content-Type: application/json

{
"useCatalogHeaderForCreatingNewItems": true,
"useCatalogHeaderForCreatingNewItems": true,}

To create new products, SKUs, or collections in a specific catalog, include CATALOG=<id> in

the first row of the CSV file, where <id> is the Catalog ID of the catalog where you want to
create the items. You must specify the ID of an existing independent catalog.
New collections without a specified parent are created in Storefront Navigation in the
specified catalog.
If you configured the catalog to have a default collection for products, new products without a
specified parent are created in that collection. Otherwise, new products without a specified
parent are created in Unassigned Products. See Import catalogs for more information.
If the catalog is associated with existing filtered catalogs, you can specify valid filtered
catalogs by Catalog ID in the filteredCatalogs column.

If products are to be directly linked to catalogs, you can specify valid independent catalogs by
Catalog IDs in the directCatalogs column. If you are importing products into a specific
catalog (that is, if the first row of the CSV file includes CATALOG=<id>), the value in a product's
directCatalogs cell must match the CATALOG=<id> Catalog ID if that product is being linked
directly to that catalog
Format for deleting property values
You can delete a property value of an item when you import it. To delete a property value,
leave the corresponding cell blank.
• If you try to delete a required property value, such as pricelist, the spreadsheet cannot be
validated and the import will fail.
• If the property has a default value, leaving the cell blank resets the value to the default.
• If you delete a cell in the spreadsheet but do not want to delete the property value during
import, you can mark the cell as ignored. See Marking Data to Ignore.
This delete format does not apply when you are adding items to collection properties. If you
format a column to prepend or append items to a collection, blank cells are automatically
ignored during import -- nothing is added or removed from the collection. See Format for
adding items to a collection property.
Marking data to ignore
When you import a spreadsheet, the file might contain data that you do not want to include in
the import, for example, columns with formulas or notes, columns containing a property that
you do not want to edit, or blank cells that might cause data to be deleted. To remove these
items from the import, you can mark columns (properties), rows (individual items), or cells
(individual property values) to be ignored by the import process.
Use the keyword IGNORE, in all capital letters, to mark data that you want to ignore during
import, as shown in the following table:

To ignore this Do this

Ignore a column of data, such as a single property Type IGNORE in the column heading (row 2).
or extra column

11-9
 Chapter 11
Import catalog items and inventory

To ignore this Do this

Ignore an item (a single row) Type IGNORE in the ID cell for the item (column 1).
Ignore a property for an item (a single cell) Type IGNORE in the cell.

Format for adding items to a collection property

You can add items to a collection property by typing an ampersand (&) before or after
the property name in the column heading of a collection property, as follows:
• Insert the ampersand at the beginning of the heading name to prepend items to
the beginning of a collection, for example &fixedChildProducts.
• Insert the ampersand at the end of the heading name to append products to the
end of a collection, for example fixedChildProducts&.
If you already use the ampersand character as part of a collection property name, you
can use a different character for appending and prepending items to collections.
The prepend and append formats simplify the process of editing collections because
you only need to include additional items and not every item in the collection. If you do
not use this format, the import process overwrites the collection property with the exact
items listed in the spreadsheet.
When you use this format, leave a cell blank to indicate that nothing should be added
to the collection. If you have formatted a column to prepend or append items to a
collection, blank cells in that column are ignored during import (nothing is added or
removed from the collection).
The following illustration shows an example of the prepend format used to add
products to collections:

Import Catalogs
In addition to the rest of the information about importing described in this topic, keep
the following points in mind when you import catalogs into Commerce.
• The first column of row one (cell A1) must contain the following string:
/atg/commerce/catalog/ProductCatalog:catalog
If you created an import template by exporting catalogs, this string will already be
in the spreadsheet and should be left exactly as exported.
• You can create a new filtered catalog by specifying its catalogVersion and
baseCatalog values. The catalogVersion column includes an integer that
specifies the type of catalog. 3 specifies a filtered catalog. The baseCatalog
column must specify the catalog ID for the independent catalog that the new
filtered catalog is based on. If the baseCatalog value does not specify an existing
independent catalog, the import will fail.
Note: You cannot change an existing catalog’s catalogVersion during import. If
you do, Commerce cannot validate the CSV file and the import will fail.
• You can create a new legacy catalog by specifying its catalogVersion value. The
catalogVersion column includes an integer that specifies the type of catalog. 1

11-10
 Chapter 11
Import catalog items and inventory

specifies a legacy catalog and 2 (default value) specifies an independent catalog. You
can create legacy catalogs only if you configured Commerce to support them. See Create
legacy catalogs for information about how to use the Admin API to enable support for
legacy catalogs.
Note: You cannot change an existing catalog’s catalogVersion during import. If you do,
Commerce cannot validate the CSV file and the import will fail.
• The rootCategories column includes a comma-separated list of Collection IDs for the
root collections in each legacy catalog. This cell must be blank if the catalogVersion
value is 2; otherwise, the import will fail.
If you are creating or updating a legacy catalog, the only values you can add to the
rootCategories cell are the IDs of root collections for the Product Catalog, including
rootCategory and nonNavigableCategory. See Understand catalogs to learn about the
Product Catalog.
• The rootNavigableCategory column includes the navigable root collection for each
catalog whose catalogVersion value is 2. The default value for this property is
rootCategory.
You cannot change the value of rootNavigableCategory for an existing catalog and this
cell must be blank if the catalogVersion value is 1; otherwise, the import will fail.
• The rootNonNavigableCategory column includes the non-navigable root collection for
each for each catalog whose catalogVersion value is 2. The default value for this
property is nonNavigableCategory.
You cannot change the value of rootNonNavigableCategory for an existing catalog and
this cell must be blank if the catalogVersion value is 1; otherwise, the import will fail.
• The defaultCategoryForProducts column includes the Collection ID of the collection
that will automatically be the parent of any product created or imported in this catalog
without a specified parent.
This column can contain values only for catalogs whose catalogVersion value is 2;
otherwise, the import will fail.

Validate and preview items

When you import a file, Commerce validates the file, first verifying that the file is formatted
correctly and contains data that can be imported, then validating the spreadsheet. If you
receive errors or warnings prior to the actual import, you can stop the task, edit the
spreadsheet to remove any errors, and then upload the file again.
After executing the validation phases and importing the spreadsheet, Commerce displays the
outcome of the import in a results dialog box.
File validation
When you select a file for import, Commerce validates the file format and the formats of the
first two rows of the spreadsheet. If there is an error in the file, a message appears on the
Import dialog.
Errors that can occur during this phase include the following:
• The file is not in CSV format.
• The repository or item type in the first column of row 1 is not valid.
• The file is missing the ID column or it is not the first column.
• Row 2 of the file contains properties that do not exist for this item type or have a
misspelled property name.

11-11
 Chapter 11
Import catalog items and inventory

• The file contains properties that are not allowed.

Note: Commerce does not export these types of properties, so if the spreadsheet
contains them, they were added to it manually and should be removed.
• The file contains a timestamp or a date property but does not have a
corresponding TIMESTAMP or DATE format in row 1.
Item validation
After the file is uploaded and passes file validation, Commerce validates all items and
displays the outcome in the Import window. You can also download a full validation
report.
The validation process determines how many imported items have changed, how
many are new, and how many are unchanged.
Note: To improve performance, Commerce does not check to see if a SKU has
duplicate variants during item validation. If you find duplicate SKU variants in your
catalogs, you can simply delete them.
Errors or warnings that can occur during item validation include:
• The value in the spreadsheet cannot be converted to the correct type for a
property, for example, a date does not include two digits for the month, or a letter
or symbol appears in a numeric property.
• A value for a required property is missing.
• A repository ID in a property value cannot be found.
If the unknown ID is for the same type of item that is being imported, the message
is a warning because the item might be created elsewhere in the spreadsheet. If it
is a different item type, the message is an error.
Note: If the ID column contains a non-existent repository ID, a new item is created
with that ID. See Format for Adding New Items.

Import products, SKUs, collections, or catalogs

Before you import your products or SKUs for the first time, you must create product
types and variant properties in Commerce. For more information, see Manage Your
Catalog.
Follow these steps to import products, SKUs, or collections from a spreadsheet:
1. On the Catalog page, click the Import button.
2. In the Import dialog, click Browse and locate the CSV file to import.
3. Click Upload File.
4. Click Validate.
Note: Depending on the size of the spreadsheet, this process could take several
minutes to complete.
The Import dialog displays the total number of changed, new, and unchanged
items, as well as any errors or warnings. To see a full validation report, click
Download Full Report.
5. Click Import.
The new and changed items are added to the catalog. You can now publish them to
your storefront.

11-12
 Chapter 11
Import catalog items and inventory

Note: If direct price editing is enabled for your Commerce store, any price changes you
import are available on the storefront without publishing. Other product changes, however,
must still be published. As a result, prices may exist on your production system before the
associated products do. These prices will be applied to the products when they are
published. See Update prices without publishing for more information.

Import inventory
Follow these steps to import inventory information for your products and SKUs from a
spreadsheet into Commerce:
1. On the Catalog page, click Manage Catalogs and select Inventory.
2. On the Manage Inventory page, click the Import button.
3. In the Import dialog, click Browse and locate the CSV file to import.
4. Click Upload File.
5. Click Validate.
Note: Depending on the size of the spreadsheet, this process could take several minutes
to complete.
The Import dialog displays the total number of changed, new, and unchanged items, as
well as any errors or warnings. To see a full report, click Download Full Report.
6. Click Import.
The new inventory data is added to your catalog and is automatically updated on your
storefront.

11-13
12
Manage Promotions
Promotions allow you to offer discounts on specific products or groups of products.
For example, you might decide to promote a range of products for Mother’s Day by
highlighting them with an image on your site’s “Welcome!” page and offering a 10 percent
discount if customers order them by a specific date.
This section describes how to work with promotions on the Marketing page. You can also use
the Commerce Admin API to programmatically create a number of promotion types that are
not available in the UI. For more information, see Create Custom Promotions.

Understand promotions
A promotion defines both the conditions an order must meet before qualifying for a discount,
and how the discount is applied.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

For example, you can specify that a customer can get a discount on a specific video game
console, on orders of more than $50, or on purchases made during July.
By default, promotions are available to all shoppers, but once you create a promotion, you
can make it available only to customers who provide a coupon code. See Add a coupon code
to a promotion for more information.
An order might qualify for more than one promotion. In this case, promotions are applied in
order of priority, with low priority numbers applied first. Commerce sorts the promotions by the
value of the Priority property. A promotion’s priority is evaluated against other promotions of
the same type. For example, item discounts are evaluated only against other item discounts,
not against order discounts. If an order qualifies for multiple promotion types, item discounts
are applied first, followed by order discounts. Promotions that are of the same type and have
the same priority have no guaranteed sequence, so the order in which they are evaluated is
undefined.
When you preview your store, you can see how your promotions behave when users shop for
items. Simply click the Preview button and then shop for items that you expect to trigger the
promotions you want to test. For more information about previewing your store, see Preview
your changes.
Commerce templates provide an easy way to create the following types of promotions:
• Order discount: The entire order is discounted. See Create an order discount promotion
for more information.
• Item discount: The shopper receives a discount on an item or items. See Create an item
discount promotion and Create a buy one get one promotion for more information.
• Shipping discount: The shopper receives discounted or free shipping. See Create a
shipping discount promotion for more information.

12-1
 Chapter 12
Understand promotion targets

Understand promotion targets

A target is an item that is discounted or given by a promotion.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This section describes how promotions are applied to items and includes the following
topics:
• Understand which items cannot be discounted by default
• Understand how add-on products affect promotions
• Understand the Discountable property for products and SKUs

Understand which items cannot be discounted

The following items cannot be discounted by Item Discount, Buy One Get One, Buy X
Get Order Discount, or Buy X Get Shipping Discount promotions. Even if you add
them to a promotion’s offer, Commerce will not consider them for the promotion.
• Items already acting as qualifiers for any other Item Discount, Buy One Get One,
Buy X Get Order Discount, or Buy X Get Shipping Discount promotion.
• Items already discounted by any other Item Discount, Buy One Get One, Buy X
Get Order Discount, or Buy X Get Shipping Discount promotion, including the
current promotion.
• Items with zero prices.
• Items with negative prices.
• Items whose prices are lower than promotion price.
Note: By default, items on sale do qualify for promotions and can be promotion
targets.

Understand how add-on products affect promotions

Add-on products let shoppers customize or enhance their purchases with optional
extras like monogramming, gift wrap, or warranties. Add-on products cannot be used
to qualify a product for a promotion, nor can they be explicitly targeted by a promotion.
However, when a promotion targets a product in the cart that includes add-ons, the
promotion discounts the total item price, that is, the price of the product plus the price
of any add-ons. For example, suppose a promotion offers 20% off all wireless
headphones. A $200 pair of headphones comes with an optional $40 replacement
warranty. When a shopper places both the headphones and the warranty in the cart,
the promotion discounts the total cost of the headphones and warranty ($240) for a
discount of $48. You cannot apply a discount only to a parent product and not its add-
ons. Keep this in mind when designing your promotions, especially when designing
promotions that might offer products with optional add-ons as free gifts. See Create
add-on products for more information.
When determining if a product with add-ons can be the target of a promotion,
Commerce considers the Discountable property of a parent product only; it does not
consider the Discountable property of any of the parent’s add-ons. For example,
suppose a set of wireless headphones is discountable but an optional charger
available as an add-on product is not discountable. When a shopper places both the

12-2
 Chapter 12
Understand currency-specific promotions

headphones and the charger in the cart, the charger will be discounted by any item or order
promotion that discounts the headphones, even though the charger’s Discountable property
is set to false. See Create and work with products to learn how to set the Discountable
property for products and SKUs.

Understand the Discountable property for products and SKUs

Each product and SKU you create in Commerce has a Discountable property. By default, the
Discountable property is set to true; this means that the product or SKU is available to be
used as a promotion target for item discount and order discount promotions. (Shipping
discount promotions ignore the Discountable property.) If you set the Discountable property to
false, the product or SKU can never be discounted by any item or order promotion, even if
you add it to a promotion’s offer condition.
Note: The Discountable property does not affect promotions from an external system that you
access with the External Promotions webhook .
Products and SKUs marked as not discountable can act as qualifiers for item and shipping
discount promotions, but they cannot contribute to the qualifying order total for order discount
promotions. For example, suppose a promotion offers 20% off orders of at least $65. If a cart
is valued at $75 but contains a $25 shirt marked as not discountable, the order does not
qualify for the promotion; the shopper must add $40 in discountable items to the cart in order
for the order to qualify for the promotion.
To prevent not-discountable items from acting as qualifiers, exclude them from a promotion in
one of the following ways:
• Add individual products or SKUs to the Buy Condition’s Excluded Items list.
• Create the following rule in the Buy Condition’s Excluded Items section:
Type = Base Product, Attribute = Discountable, Value = False

Understand currency-specific promotions

If your store uses price groups to support multiple currencies, you can specify that a
promotion applies only to items purchased in specific currencies.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

For example, you can create an order discount called “Spend 100 Euros, get 10 Euros off”
that applies to the product prices in all price groups that contain the currency Euro. Or you
can create a promotion that applies only if the shopper is paying with a specific credit card.
When you create a promotion, you use the Price Groups field to specify the price groups for
which the promotion is valid.
If you select one or more price groups, the promotion is valid only for those price groups. If
you leave the Price Groups field blank, the promotion is valid for all price groups.

Understand audience-specific promotions

An audience represents a segment of the shoppers that visit your store.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

12-3
 Chapter 12
Understand site-specific promotions

You define an audience by creating a set of rules based on attributes of the shopper
profile. You can create promotions that can be claimed only by shoppers who are
members of specific audiences. For example, a 20% off store-wide promotion could
apply only to employees of a certain company or shoppers with a high average order
value.
When you create a promotion, you use the Target Audience field on the Availability tab
to select the audiences whose members are eligible for the promotion. If you select
one or more audiences, the promotion is valid only for members of those audiences. If
the Target Audience field contains no audiences, all shoppers are eligible for the
promotion, assuming they meet the other qualifying conditions.
You can select both enabled and disabled audiences for a promotion. If you select a
disabled audience, the promotion is not valid for that audience until you enable the
audience.
If an audience you added to a promotion is later deleted, Commerce does not
automatically remove the deleted audience from the promotion, but adds an icon that
indicates it has been deleted. You should remove deleted audiences from the
promotion. If all the audiences associated with a promotion are deleted, the promotion
will never be available to any shoppers.
See Define Audiences for more information about creating and managing audiences.

Understand site-specific promotions

If your store supports multiple sites, you can specify that a promotion applies to items
purchased only from specific sites.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Your Commerce instance initially has a single site, or store. You can, however, run
multiple sites from a single Commerce instance. Each site corresponds to a store. For
example, you might have a site that sells jerseys for a specific team, and you may
want to apply a promotion only to items sold on that site.
When you create a promotion, you use the Sites field to specify the sites on which the
promotion is valid. If you select one or more sites, the promotion is valid only for those
sites. If you select the Applies to All checkbox, the promotion is valid on all sites.

Copy an existing promotion

Creating a new promotion based on an existing one lets you easily create a number of
similar promotions, and lets you reuse promotions that were successful in the past.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

When you copy an existing promotion, the following values are automatically copied to
the new promotion:
• Display name (By default, this will be set to the name of the promotion that was
copied, followed by (copy). For example, Summer Sale (copy).
• Description
• Price groups

12-4
 Chapter 12
Create an order discount promotion

• All condition and offer properties

• Priority
• Folder
• Excluded promotions
When you copy an existing promotion, the following values are not copied to the new
promotion:
• Start and end dates
• Promotion ID (A new ID is automatically assigned when you save the promotion.)
• Stacking rules
• Coupon or coupon batch
• Enabled status
• Any translations for shopper-visible properties, such as the name of the promotion. You
can copy an existing promotion only in the store’s default language. Once you save the
copied promotion, you can translate properties into other languages your store supports.
See Localize Your Store for more information.
You can copy promotions created on the Promotions page of the administration interface. You
cannot copy custom promotions created with the rawPmdlTemplate promotion template. For
more information about custom promotions, see Create Custom Promotions.
To copy an existing promotion:
1. On the Promotions page, click the row of the promotion to copy and then click the Copy
button.
Click anywhere in the row except on the link that is the promotion’s name. Clicking that
link opens the existing promotion.
2. Enter information about the promotion that was not copied.
3. Click Save.
4. (Optional) Create a coupon code that customers must provide to redeem the promotion.
See Add a coupon code to a promotion for more information.

Create an order discount promotion

An order discount promotion discounts an entire order.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Commerce includes the following order discount promotion templates:

• Spend Y for Order Discount discounts an order when a shopper spends a specified
amount. You can discount orders by a fixed amount, such as $20, or by a percentage,
such as 15%.
You can configure this promotion to apply bigger discounts as the value of an order
increases. For example, a promotion might discount a $75 order by 10%, a $100 order by
15%, and an order of $150 or more by 20%.
• Spend Y in X Get Order Discount discounts an order when the shopper spends a
specified amount in specified product areas. For example, Spend $50 in Back-to-School
Fashions, Get 20% Off Your Entire Order.

12-5
 Chapter 12
Create an item discount promotion

• Buy X Get Order Discount discounts an order when a shopper buys something in
a specified product area. For example, Buy 2 Kids Backpacks, Get 10% Off Your
Entire Order. See Understand promotion targets for information about how this
type of order discount interacts with item discounts.
You can configure this promotion to discount any order, regardless of how much
shoppers spend or what items they purchase.
When Commerce sends the JSON representation of an order in the body of a
webhook or a response to a REST API request, order discount promotions are listed
individually in an orderDiscountInfos map within each cart item's JSON
representation. The map includes the promotion ID, discount amount, and coupon
codes (if applicable) for each order discount applied to the order. The following sample
shows part of an Order Submit webhook body for an order that is discounted by two
different order discount promotions.

...
"orderDiscountInfos": [
{
"couponCodes": [],
"amount": 59.7,
"promotionId": "orderDiscount"
},
{
"couponCodes": ["coupon101"],
"amount": 3.65,
"promotionId": "promo10001"
}
],
...

To create a new Order Discount promotion, follow these steps:

1. On the Promotions page, click New Promotion and select Spend Y for Order
Discount, Spend X in Y Get Order Discount, or Buy X Get Order Discount.
2. Enter the name, description, and price groups for the promotion. See Enter
general promotion information for details about each field.
3. Enter condition and offer details for the promotion. See Enter condition and offer
information for details about each field.
4. On the promotion’s Availability tab, define the promotion’s lifecycle and enter
information that determines when the promotion is active and usable. See Enter
promotion availability information for details about each field.
5. (Optional) Specify promotions that cannot be combined with this one. See Exclude
promotions for more information.
6. Click Save.
7. (Optional) Create a coupon code that customers must provide to redeem the
promotion. See Add a coupon code to a promotion for more information.

Create an item discount promotion

An item discount promotion discounts one or more qualifying items.

12-6
 Chapter 12
Create an item discount promotion

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Oracle Commerce includes the following types of item discount promotion templates:
• Get Item Discount automatically discounts one or more qualifying items without requiring
the shopper to make any other purchases. For example, 20% Off All Kids’ Backpacks.
• Spend Y in X Get Item Discount discounts one or more qualifying items when the
shopper spends a specified amount in specified product areas. For example, Spend $100
in Back-to-School Fashions, Get 20% Off Kids’ Backpacks.
You can create a promotion that discounts one of more items when a customer spends the
specified amount anywhere in your store (Spend Y Get Item Discount) by specifying that
shoppers can spend the minimum amount on any item. For example, Spend $100, Get 20%
Off Kids’ Backpacks. See Enter condition and offer information for details.
Each item in a shopper’s cart can be discounted by only one item discount promotion, even if
it qualifies for more than one item discount. Item discount promotions are evaluated in order
of priority, with low priority numbers applied first. Item discount promotions that have the
same priority have no guaranteed evaluation order. For example if a shirt qualifies for three
item discount promotions, and all three promotions have the same priority, there is no way to
be certain which promotion will be applied to the shirt when a shopper places it in her cart.
To create a new Get Item Discount or Spend Y in X Get Item Discount promotion:
1. On the Promotions page, click New Promotion and select Get Item Discount or Spend
Y in X Get Item Discount.
2. Enter the name, description, and price groups for the promotion. See Enter general
promotion information for details about each field.
3. Enter condition and offer details for the promotion. See Enter condition and offer
information for details about each field. See Sample item discount promotion for an
example that explains how different condition and offer settings can affect the discount.
Note: The Get Item Discount promotion has no buy condition.
4. On the promotion’s Availability tab, define the promotion’s lifecycle and enter information
that determines when the promotion is active and usable. See Enter promotion
availability information for details about each field.
5. (Optional) Specify promotions that cannot be combined with this one. See Exclude
promotions for more information.
6. Click Save.
7. (Optional) Create a coupon code that customers must provide to redeem the promotion.
See Add a coupon code to a promotion for more information.

Sample item discount promotion

This section describes a promotion called Summer Skirt Sale. When a shopper spends $100
anywhere in the Bags and Luggage collection, the promotion discounts one skirt by 25%. The
items to include and exclude for offer are the same as items in buy condition. At least one
qualifying item must be purchased. The discount order is least expensive item discounted
first and the promotion uses list prices to sort the discount order. The promotion discounts a
maximum of one item.
A shopper’s cart contains the following items:
• One backpack, list price $100

12-7
 Chapter 12
Create a buy one get one promotion

• One skirt, list price $100, on sale for $75

• One skirt, list price $200, on sale for $50
The backpack fulfills the promotion condition. The discount is applied to the skirt that
costs $75, not to the one that costs $50, because the less-expensive skirt has a higher
list price.

Create a buy one get one promotion

A buy one get one (sometimes called BOGO or Buy X Get Y) promotion discounts an
item when a customer buys another, often similar, item.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

A common buy one get one condition is that the shopper buys an item in a collection
and receives a discount on a second item in that collection. For example, when a
shopper buys two tops, she gets one for 50% off. A common Buy X Get Y condition is
that a shopper buys one or more items and receives a discount on a related item. For
example, when a shopper buys a pair of hiking boots, she gets a free pair of hiking
socks.
To create a new buy one get one promotion, follow these steps:
1. On the Promotions page, click New Promotion and select Buy One Get One.
2. Enter the name, description, and price groups for the promotion. See Enter
general promotion information for details about each field.
3. Enter condition and offer details for the promotion. See Enter condition and offer
information for details about each field. See Sample buy one get one promotion for
an example that explains how different condition and offer settings can affect the
discount.
4. On the promotion’s Availability tab, define the promotion’s lifecycle and enter
information that determines when the promotion is active and usable. See Enter
promotion availability information for details about each field.
5. (Optional) Specify promotions that cannot be combined with this one. See Exclude
promotions for more information.
6. Click Save.
7. (Optional) Create a coupon code that customers must provide to redeem the
promotion. See Add a coupon code to a promotion for more information.

Sample buy one get one promotion

This section describes a promotion called Summer Shoes: Buy One Get One. When a
shopper buys one pair of shoes from the collection Ladies Shoes, the promotion
discounts another pair from that collection by 50%. The buy condition includes the
collection Ladies Shoes but excludes its child collection Ladies Designer Shoes. The
items to include and exclude for offer are the same as items in buy condition. At least
one qualifying item must be purchased. The discount order is least expensive item
discounted first and list prices are used to sort the items. The promotion discounts a
maximum of 2 items.
A shopper’s cart contains the following items:
• One pair of ladies sandals, list price $100

12-8
 Chapter 12
Create a shipping discount promotion

• One pair of ladies designer boots, list price $800

In this case, the discount is not applied to either item. The designer boots are excluded from
the buy condition, so the sandals cannot be discounted. While the sandals do count toward
the buy condition, the boots are excluded from the offer, so they cannot be discounted.
Another shopper’s cart contains the following items:
• One pair of ladies sandals, list price $100
• One pair ladies sandals, list price $75
In this case, the $75 sandals receive the discount. If you edit the promotion to apply the
discount to the most expensive item first, then the $100 sandals receive the discount.

Create a shipping discount promotion

A shipping discount promotion offers free or discounted shipping via shipping methods you
associate with the promotion.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Shipping discount promotions can discount both internally-priced and externally-priced

shipping methods. Shipping discount promotions you create with templates on the
Promotions page apply the shipping discount to an entire order. To apply a shipping discount
to an individual shipping group within an order, you must create a custom promotion with the
Commerce Admin API.
Note: Shipping surcharges are not affected by shipping promotions and are added to the
order total during checkout. See Manage Your Catalog and Configure Shipping for more
information about shipping methods and shipping surcharges.
You can create the following types of shipping discounts:
• Get Shipping Discount discounts shipping for all orders with no required buy condition
• Spend Y Get Shipping Discount discounts shipping when the shopper spends at least a
specified amount.
• Spend Y in X Get Shipping Discount discounts shipping when the shopper spends at
least a specified amount in specified product areas. For example, Spend $50 in Back-to-
School Fashions, Get Free Shipping On Your Entire Order.
• Buy X Get Shipping Discount discounts shipping when the shopper purchases specified
items.
To create a new shipping discount promotion:
1. On the Promotions page, click New Promotion and select Get Shipping Discount,
Spend Y Get Shipping Discount, Spend Y in X Get Shipping Discount, or Buy X Get
Shipping Discount.
2. Enter the name, description, and price groups for the promotion. See Enter general
promotion information for details about each field.
3. Enter condition and offer details for the promotion. See Enter condition and offer
information for details about each field. See Sample buy one get one promotion for an
example that explains how different condition and offer settings can affect the discount.
Note: Get Shipping Discount does not require a buy condition.

12-9
 Chapter 12
Create a gift with purchase promotion

4. On the promotion’s Availability tab, define the promotion’s lifecycle and enter
information that determines when the promotion is active and usable. SeeEnter
promotion availability information for details about each field.
5. (Optional) On the promotion’s Exclusion Rules tab, specify promotions that cannot
be combined with this one. See Exclude promotions for more information.
6. Click Save.
7. (Optional) Create a coupon code that customers must provide to redeem the
promotion. See Add a coupon code to a promotion for more information.

Create a gift with purchase promotion

Gift with purchase promotions let you give a customer a free item as part of their order.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You can create two types of gift with purchase promotions:

• Gift with Item Purchase gives the shopper a free gift with a purchase. You can
offer a gift with any purchase or with the purchase of a specific item. This
promotion can apply only once per shopping cart. Gift items cannot act as
qualifiers for the promotion. For example, suppose you create a promotion that
offers a free votive candle with any purchase. If the shopper adds one votive
candle to the cart, that candle is not repriced to free. If the shopper then adds
another item to the cart, that item qualifies the cart for the promotion, and the
votive candle is repriced to free.
• Spend Y Get Gift with Purchase gives the shopper a free gift when they spend a
specified amount. For example, “Spend $100, get a free $10 gift card.” Gift items
cannot act as qualifiers for the promotion, so if a shopper adds a gift item to the
cart, its price does not count toward the Spend Y total. This promotion can apply
only once per shopping cart; if a shopper adds two of the qualifying item, only one
will be repriced to free.
When a shopper’s cart qualifies for a gift with purchase promotion, one of the following
things happens:
• If no item in the cart meets the offer criteria, the gift item is automatically added to
the cart. The gift item cannot act as a qualifier for other promotions.
• If the shopper has already added the gift item to their cart, the item is repriced to
be free. Once the gift item is repriced, it can no longer act as a qualifier for other
promotions.
If the shopper removes the gift from a qualifying cart, Commerce does not
automatically re-add the gift while the cart still qualifies for the promotion. There are
two ways to add the gift again:
• If the shopper re-adds the gift item to the cart, the item is repriced to free if the cart
still qualifies for the promotion.
• If the cart becomes unqualified (for example, if the shopper removes items
required for the buy condition) and then qualified again (for example, if the
shopper adds back items required for the buy condition), Commerce automatically
re-adds the gift.

12-10
 Chapter 12
Define a promotion

When an item appears in an order object (for example, in the body of an Order Submit
webhook), the property gwp specifies whether the item was given as part of a gift with
purchase promotion. For gift items, the value of the gwp property is true; for all other items,
the value is false. For example:

"gwp":true,

To create a new gift with purchase promotion, follow these steps:

1. On the Promotions page, click New Promotion and select Gift with Item Purchase or
Spend Y Get Gift with Purchase.
2. Enter the name, description, and price groups for the promotion. See Enter general
promotion information for details about each field.
3. Enter condition and offer details for the promotion. See Enter condition and offer
information for details about each field.
4. On the promotion’s Availability tab, define the promotion’s lifecycle and enter information
that determines when the promotion is active and usable. See Enter promotion
availability information for details about each field.
5. (Optional) Specify promotions that cannot be combined with this one. See Exclude
promotions for more information.
6. Click Save.
7. (Optional) Create a coupon code that customers must provide to redeem the promotion.
See Add a coupon code to a promotion for more information.

Define a promotion
You define a promotion by entering basic descriptive information, the buy condition and offer,
and the promotion's availability.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This topic contains the following sections that describe how to define a promotion:
• Enter general promotion information
• Enter condition and offer information
• Enter promotion availability information
• Understand promotion filters

Enter general promotion information

The following table describes the basic properties for a promotion. You set these properties
on the promotion’s General tab.

Property Description
Display Name (required) Short, descriptive name that identifies the
promotion.
Description Short description that helps you to identify a
promotion in the administration interface. The
description does not appear on your store.

12-11
 Chapter 12
Define a promotion

Property Description
Sites Select the sites this promotion applies to. Select
Applies to all for a promotion that can be used on
all sites. By default, the promotion applies to all
sites. See Understand site-specific promotions for
more information.
Price Groups Select the price groups this promotion applies to. If
you leave this field blank, the promotion applies to
all price groups. See Understand currency-specific
promotions for more information.

Enter condition and offer information

The condition and offer determine how your promotion works, as well as what the
qualifying behavior is, what type of discount results, and if there are any exclusions.
• The buy condition describes items or spend amount that qualify for the discount.
(Not all promotions require a buy condition. For example, the Get Item Discount
and Get Order Discount promotions do not require a buy condition.
• The offer describes items that are discounted by the promotion. Commerce
evaluates the condition rules first before evaluating the offer rules to find target
items for the discount.
You set condition and offer properties on the promotion’s General tab.
The following table describes the buy condition properties for Commerce promotions.
Note: The Get Item Discount and Get Shipping Discount promotions do not have buy
conditions.

Property Description
Minimum Spend The spend threshold for promotions that
require a shopper to spend a minimum
amount.
Minimum Spend applies to the following
promotions: Spend Y Get Gift With Purchase,
Spend Y in X Get Item Discount, Spend Y for
Order Discount, Spend Y in X Get Order
Discount, Spend Y in X Get Shipping
Discount, and Spend Y Get Shipping Discount.
If you are creating a Spend Y For Order
Discount promotion, you can specify one or
more spend tiers and assign a discount to
each tier. For example, order totals from $75
to $99.99 are discounted by 10%, order totals
from $100 to $149.99 are discounted by 15%,
and order totals of $150 or more are
discounted by 20%.
To create a promotion without tiers, that is, one
that provides the same spend threshold for all
orders, enter the Minimum Spend value, leave
the Range End value blank, and then enter a
discount amount.

12-12
 Chapter 12
Define a promotion

Property Description
Get Discount With Any Order For Buy X Get Order Discount promotions,
specifies that the shopper can make any
purchase anywhere in your store. If you do not
select this option, you must select individual
products and collections that qualify for the
promotion (Included Items).
Spend On Any Item For Spend Y in X promotions, specifies that
the shopper can spend the Minimum Spend
amount anywhere in your store. If you do not
select this option, you must select individual
products and collections that qualify for the
promotion (Included Items).
Included Items Products, collections, and SKUs that qualify for
the discount. See Include or exclude products,
SKUs, or collections for more information.
To qualify everything in your store for the
discount, select Include Entire Catalog. Even if
you select this option, you can still select
products and collections that cannot qualify for
the promotion (Excluded Items).
Included Items applies to the following
promotions: Get Item Discount, Buy One Get
One, Gift With Item Purchase, Spend Y in X
Get Item Discount, Spend Y in X Get Order
Discount, Buy X Get Order Discount, Spend Y
in X Get Shipping Discount, and Buy X Get
Shipping Discount.
Excluded Items Products, collections, and SKUs that cannot
qualify for the promotion. Excluded items
always take precedence over included items.
SeeInclude or exclude products, SKUs, or
collections for more information.
Excluded Items applies to the following
promotions: Get Item Discount, Buy One Get
One, Gift With Item Purchase, Spend Y in X
Get Item Discount, Spend Y in X Get Order
Discount, Buy X Get Order Discount, Spend Y
in X Get Shipping Discount, and Buy X Get
Shipping Discount.
Give Gift With Any Order For a Gift With Item Purchase promotion,
specifies that the promotion should apply to
any order without requiring the purchase of
specific products. If you select this option, you
will no longer see the Included items, Excluded
items, and Number of items required to buy to
get offer fields.
Number of Items Required to Buy to Get Offer) For a Buy One Get One promotion, the
number of items the shopper must purchase in
order to receive the discount.

The following table describes the offer properties for Commerce promotions.

12-13
 Chapter 12
Define a promotion

Property Description
Discount Type For order promotions, select Amount Off or
Percent.
For shipping promotions and item promotions
(except gift with purchase), select Amount Off,
Percent, Fixed Price, or Free.
Discount Amount Enter the amount of the discount or, if the
Discount Type is Fixed Price, enter the price of
the item. If the Discount Type is Free, this field
does not appear.
Included Items Products, collections, or SKUs that are
discounted by the promotion. SeeInclude or
exclude products, SKUs, or collections for
more information.
To allow everything in your store to be
discounted by the promotion, select Include
Entire Catalog. Even if you select this option,
you can still select products, collections, and
SKUs that cannot be discounted by the
promotion (Excluded Items).
This offer property applies to the following
promotions: Get Item Discount, Buy One Get
One, and Spend Y in X Get Item Discount.
Excluded Items Products, collections, or SKUs that cannot be
discounted by the promotion. Excluded items
always take precedence over included items.
SeeInclude or exclude products, SKUs, or
collections for more information.
This offer property applies to the following
promotions: Get Item Discount, Buy One Get
One, and Spend Y in X Get Item Discount.
Items to Include and Exclude For Offer Are the For Buy One Get One promotions, you can
Same as Items in Buy Condition select this option instead of selecting items to
include or exclude for the offer.
If you update the included and excluded items
in the condition, the offer is automatically
updated when you save the promotion.
Number of Items to be Discounted as Part of Prevents discounting an unlimited number of
the Offer qualifying items. Enter the number of items
that can receive the discount. For instance, if a
shopper purchases six items in the discounted
category, you might discount five of them. By
default, this is set to unlimited.
This offer property applies to the following
promotions: Get Item Discount, Buy One Get
One, and Spend Y in X Get Item Discount.

12-14
 Chapter 12
Define a promotion

Property Description
Order by Which Discount is Applied Select whether the discount should be applied
to the lowest or the highest priced items in the
order first. By default, discounts are applied to
the lowest-priced items first.
This setting applies only if you specified a
number of items to be discounted as part of
the offer. If the offer discounts unlimited items,
this setting is ignored.
This offer property applies to the following
promotions: Get Item Discount, Buy One Get
One, and Spend Y in X Get Item Discount.
Price to Use for Sorting Items Select whether to use list prices or lowest
discounted prices when Commerce
determines which items the promotion should
discount. A product’s lowest discounted price
can be discounted by one or more of the
following: a price group’s sale price, promotion
discounts, or integration with an external
pricing system.
See Sample item discount promotion for
details about how this setting affects items
discounted by a promotion.
This setting applies only if you specified the
number of items to be discounted as part of
the offer. If the offer discounts unlimited items,
this setting is ignored.
This offer property applies to the following
promotions: Get Item Discount, Buy One Get
One, and Spend Y in X Get Item Discount.
Include Shipping Methods For shipping promotions, the shipping methods
that qualify for the discount.
To select shipping methods, begin by typing or
pasting some text in the Add Shipping
Methods box.
If a shipping method has an internal name
assigned, it appears in parentheses after the
shipping method's display name. Internal
names are hidden from shoppers but let you
create multiple shipping methods with the
same display name.
Select a Gift For gift with purchase promotions, the product
given as a free gift by the promotion. You can
select any single product from your catalog.
Gift Handling When Cart No Longer Meets For gift with purchase promotions, specifies
Buy Condition what should happen to a gift item in the cart
when the cart no longer qualifies for the
promotion. Select one of the following options:
Automatically remove gift item from cart
Leave gift in cart and reprice item

12-15
 Chapter 12
Define a promotion

Enter promotion availability information

The following table describes the properties that define a promotion’s lifecycle by
specifying when it is active and usable. These properties are available on a
promotion’s Availability tab.

Property Description
Start Date / Time Date and time the promotion becomes
available.
End Date / Time Date and time the promotion is no longer
available.
Target Audience Select one or more audiences whose
members are eligible for this promotion. By
default, no audiences are specified and the
promotion is available to all shoppers.
Audiences are listed alphabetically by display
name. Both enabled and disabled audiences
appear in the list. See Understand audience-
specific promotions for more information.
Coupon Code The code customers use to redeem a coupon
for this promotion. Coupon codes are case-
sensitive.
Note: You must save a new promotion before
you can add a coupon code to it.
See Add a coupon code to a promotion for
more information.
Priority (required) The priority of the promotion. Promotions are
applied in order of priority, with low priority
numbers applied first. Commerce sorts the
promotions by the value of this property.
A promotion’s priority is evaluated against
other promotions of the same type. For
example, item discounts are evaluated only
against other item discounts, not against order
discounts.
If an order qualifies for multiple promotion
types, item discounts are applied first, followed
by order discounts, then shipping discounts.
Promotions that are of the same type and have
the same priority have no guaranteed
sequence, so the order in which they are
evaluated is undefined.
Enabled Specifies whether this promotion can be used
with a qualifying order. This setting is turned
on by default, but a promotion’s availability
also depends on any start and end dates you
set. If Enabled is turned off, the promotion
cannot be used regardless of the start and end
dates.

12-16
 Chapter 12
Define a promotion

Property Description
Card IIN Range Credit cards use an international Issuer
Identification Number (IIN) that identifies the
type of card, for example, MasterCard or
American Express. The first 6 digits of a credit
card contain the IIN. You can create a range of
numbers that identify a specific credit card
issuer, allowing you to create credit card-
specific promotions. Entering a range of
numbers allows you to identify specific credit
cards that qualify for this promotion.
You can use dashes (-) and commas (,) to set
ranges. For example, 2 – 3 would include all
credit cards that have an IIN between 200000
and 399999. The end of the range must be
larger than the starting range. Use commas to
specify a series of ranges, such as 222 (all
numbers between 222000 and 222999), 444
(all numbers between 444000 and 444999).
These conventions can be used together, for
example, 1011, 122122-122925, 133-139, 15.
By default, promotions are not limited to any
credit card type or range.
Note: Although it is possible to assign IIN
ranges when working with CyberSource
payment gateways, the promotions will not
apply.
Folder The folder where this promotion is stored. By
default, no folder is selected. If you created the
promotion by copying an existing promotion,
then the value is the same folder as the
promotion you copied. See Organize
promotions in folders for more information.
Custom Defined Label A custom property associated with the
promotion, if one has been configured.
(Custom promotion properties are configured
with the Admin API. See Create custom
properties for promotionsCreate custom
properties for promotions for more
information.)

Understand promotion filters

Promotions can be filtered using the options provided on the promotion's Advanced tab.
Filters allow you to perform a number of actions, such as exclude or include qualified items,
or include items that are on sale. Filters are based on qualifying conditions or offers
presented by the promotion. To implement a filter, perform the following steps:
1. Use the administration interface to go to Promotions.
2. Select the promotion to edit.
3. Click the Advanced tab. The screen displays the filters that are available for that
promotion.
4. Use the drop down menu to select the filter settings. If you do not select a setting, the
default settings are used.

12-17
 Chapter 12
Define a promotion

The following filters are available for promotions:

Filter Description Used on promotions

Qualified Items (Any This conditional filter allows Item, Order or Shipping
promotion) you to identify if a qualifier can promotions.
be used only once per
promotion. If you select
Include, qualifiers will be used
only once per promotion.
Discounted Items (Any This conditional filter allows Item, Order or Shipping
promotion) you to include or exclude promotions.
items discounted by any
promotion and allow them to
act as a qualifier for other
promotions.
Discounted Items (Current This conditional filter allows Item promotions.
promotion) you to determine if items
discounted by the current
promotion can act as a
qualifier for other promotions
Items on Sale This conditional filter identifies Item, Order or Shipping
if items that have a sale price promotions.
can act as qualifiers.
Items with Zero Prices This conditional filter identifies Item, Order or Shipping
if an item with a zero price can promotions.
act as a qualifier for this
promotion.
Items with Negative Prices This conditional filter identifies Item, Order or Shipping
if items with negative prices promotions.
can act as qualifiers. If you
select Include, then items with
negative prices will act as a
qualifier.
Qualified Items This offer filter includes or Item promotions only.
excludes items that have acted
as qualifiers for another
discount. If you include these
items, any item that acted as a
qualifier for another discount
can be receive the discount.
Discounted items (Any This offer filter determines if Item promotions only.
promotion) items that have already been
discounted by the current
promotion can receive the
discount again. If you include
discounted items, the items
can receive the discount
again.
Discounted Items (Current This offer filter includes or Item promotions only.
promotion) excludes discounted items
from the current promotion.
Items on Sale This offer filter includes or Item promotions only.
excludes items that were
priced with a sales price from
receiving the discount.

12-18
 Chapter 12
Enable and disable promotions

Filter Description Used on promotions

Items with Zero Prices This offer filter includes or Item promotions only.
excludes items that have zero
prices.
Items with Negative Prices This offer filter identifies if Item promotions only.
items with negative prices can
receive the discount. If you
include items with negative
prices, they will receive the
discount.
Items with Prices Lower than This offer filter includes or Item promotions only.
Promotion Price (Fixed Price excludes items that have a
promotions only) price lower than the promotion
price. This applies to fixed
price promotions only.

Enable and disable promotions

You can enable and disable promotions within qualifying orders.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

A promotion is available to be used with a qualifying order if both of the following are true:
• You have selected the Enabled checkbox on the promotion's Availability tab.
• The qualifying order is placed during the time specified by the promotion’s start and end
dates.
The easiest way to disable a promotion is to uncheck its Enabled checkbox.
Important: Deleting assets, such as products, catalogs, shipping methods, etc., can result in
discrepancies in your system, which may produce errors. It is recommended that you disable
assets instead of delete them.

Organize promotions in folders

You can create folders to organize your promotions so they are easier to find and work with.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This section includes the following topics:

• Create a promotions folder
• Edit a promotions folder
• Add promotions to a folder
• Delete a promotions folder

Create a promotions folder

To create a promotions folder, follow these steps:
1. On the Promotions page, click the Manage Folders button.

12-19
 Chapter 12
Organize promotions in folders

2. Click Create New Folder.

3. Enter a name for the folder and, if you want it to be a child of another folder, click
the Locate Folder Under drop-down list and select a parent folder.
4. Click Create.

Edit a promotions folder

You can change a folder’s name and parent folder. You cannot change a folder’s ID.
To edit a promotions folder, follow these steps:
1. On the Promotions page, click the Manage Folders button.
2. Click the edit icon for the folder you want to edit.
3. Change the folders name and/or parent folder.
4. Click Save.

Add promotions to a folder

You can add one or more promotions to a folder by selecting them from the
Promotions list and then selecting a folder to add them to. You can also add a single
promotion to a folder by specifying a folder while creating or editing the promotion.
To add one or more promotions to a folder, follow these steps:
1. On the Promotions page, select the promotions to move to a folder.
2. Click the Manage Folders button.
3. Select a folder from the list.
Note: You can add the promotions only to an existing folder; you cannot create a
folder and add the selected promotions to it in a single step. If you click Create
New Folder in this dialog, Commerce does create a new folder, but does not add
the selected promotions to it.
To change a promotion’s folder property follow these steps:
1. On the Promotions page, click the promotion to edit.
2. Select a folder from the Add Promotion To list.
3. Click Save.

Delete a promotions folder

Deleting a promotions folder does not also delete its contents. If you delete a folder
that contains promotions or other folders, they are automatically moved to the top level
in the folder list.
Important: Deleting assets, such as products, catalogs, promotions, etc., can result in
discrepancies in your system, which may produce errors. It is recommended that you
disable assets instead of delete them.
To delete a promotions folder, follow these steps:
1. On the Promotions page, click the Manage Folders button.
2. Click the edit icon for the folder you want to delete.
3. Click Delete.

12-20
 Chapter 12
Include or exclude products, SKUs, or collections

4. Confirm that you want to delete the folder or click Cancel to keep the folder.

Include or exclude products, SKUs, or collections

Most promotions must include at least one item that a shopper must buy to qualify their order
for the discount (called the buy condition) and at least one item that can be discounted by the
promotion (called the offer).

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You can specify products to include or exclude from a promotion’s condition or offer using any
combination of the following:
• Select one or more products from your catalog. All SKUs for a selected product are
included or excluded from the buy condition or offer.
• Select one or more collections from your catalog. All products in a selected collection are
included or excluded from the buy condition or offer.
• Select one or more SKUs from your catalog.
• Create one or more rules that automatically select products based on product, SKU, or
variant properties you specify. For example, suppose you want to exclude all premium
brands from a promotion that discounts athletic shoes. You would create a rule that
includes the product property Brand and specifies which brands to exclude. See Create
rules to include or exclude items to learn how to create a rule.
Keep the following in mind when you include and exclude items from a buy condition or offer:
• Excluded items always take precedence over included items. For example, if an offer
includes the collection Movie Store Root but excludes its child collection Clearance
Movies, no items in Clearance Movies will be discounted by the promotion.
However, if you include Clearance Movies but exclude its parent, Movie Store Root, then
no movies, even those in the Clearance Movies collection, can be discounted by the
promotion.
• Commerce does not prevent you from adding the same item to both the included and
excluded items lists. In this case, the item is excluded.
• If an included or excluded items list uses a combination of selected products, selected
collections, and a set of rules, Commerce checks each item in the shopper’s cart to see if
it matches any of the products in the list or the set of rules.
• Promotions identify included and excluded products and collections by their IDs. If an
item is part of a promotion and you reassign its ID to different item, the promotion
automatically uses the new item with the reassigned ID. This may cause unexpected
results.
To select products, collections, or SKUs to include or exclude from a buy condition or offer,
follow these steps:
1. On a promotion’s details page, under Included Items or Excluded Items, click the Edit
button next to the Products or Collections box.
2. Select a product or collection from the list. You can filter the list by typing or pasting some
text in the Products or Collections box.
The filter control matches letters or numbers that you type, wherever they appear in the
name or ID, not just at the beginning. Usually, as you type more characters, there are
fewer matches. When you see the item you want, select it.

12-21
 Chapter 12
Include or exclude products, SKUs, or collections

3. Click Add Selected.

4. Click Done when you finish adding products or collections.

Create rules to include or exclude items

This section describes how to create a rule for a buy condition or offer. A rule
automatically selects items based on product, SKU, or variant properties. For example,
suppose you created a custom, internal property called Do Not Discount on the base
product type. Merchandisers select this option for products in your catalog that should
never be discounted by any promotion. To make sure that no promotions ever discount
these products, create a rule for each promotion’s offer that includes the base product
property Do Not Discount and specifies that its value should be True.
To create a rule that specifies products to include or exclude from a buy condition or
offer, follow these steps:
1. On a promotion’s details page, under Included Items or Excluded Items, click the
New Rule button.
2. Select a type of property to use from the Type list. You can select only one type
per rule:
• Base Product lets you select from all the product properties associated with
your catalog’s base product type, including custom properties you created.
• Base SKU lets you select from all the SKU properties associated with your
catalog’s base product type. SKUs created from the base product type can
have SKU properties but not variant properties.
• Custom Product Type Product lets you select from all the custom product
properties associated with a custom product type you created in your catalog,
where Custom Product Type is the product type’s name.
• Custom Product Type SKU or Variant lets you select a SKU property or variant
property from a custom product type you created in your catalog, where
Custom Product Type is the product type’s name.
See Create and edit product types for more information about product properties
and SKU properties. See Create and work with SKUs for more information about
variant properties.
3. Select a property from the Attribute list. The available properties depend on the
Type you selected in the previous step. You can select only one attribute per rule.
• For Base Product, Commerce displays all the product properties associated
with your catalog’s base product type (except ID), including custom properties
you created.
• For a custom product type, Commerce displays all the custom product
properties associated with the product type you selected. None of the base
product type properties are available in this list.
• For Base SKU, Commerce displays all the SKU properties associated with the
base product type, including custom SKU properties you created.
• For a custom product type SKU or Variant, Commerce displays all the SKU
and variant properties associated with the product type you selected. None of
the base SKU properties are available in this list.
4. Select an operator that links the property to a value that you will specify in the next
step.

12-22
 Chapter 12
Exclude promotions

The operators you see depend on the kind of property you selected as an attribute. For
example, if you select the base product type property Arrival Date, the available
operators are Before and After.
5. Select or enter a value for the property.
For some values, such as variant values, Commerce displays a list for you to choose
from. (If you selected a custom product type SKU or Variant, the list includes both SKU
values and variant values, with any SKU values appearing first in the list.) For others,
such as Availability Date or Brand, you must type in a value. The rule editor does not
validate any text or numeric values you type, so take care when you enter values and
make sure you test promotions before they go live. The rule editor also does validate
date values.
6. Click Done when you finish creating the rule.
7. If you create more than one rule for an included or excluded items list, select one of the
following Rule Matching options to specify how the rules in this set behave together:
• Match Any Rule: (default) If an item in a shopper’s cart matches any rule in the set,
that rule applies.
• Match All Rules: If an item in a shopper’s cart matches all the rules in the set, all the
rules apply. If the item matches only some of the rules but not all, none of the rules
apply.
8. Click Save.

Exclude promotions
Exclusion rules prevent customers from taking advantage of unintended synergy among your
promotions by letting you specify promotions that can never be combined with the current
promotion.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

For example, if a promotion offers 25% off all soccer equipment, you might want to specify
that another promotion, which offers 10% off all items in your catalog, cannot be combined
with it.
Keep the following in mind when you create exclusion rules for a promotion:
• Excluded promotions must have a lower priority than the promotion that is excluding
them.
• Use caution when excluding promotions, to prevent confusion as to exactly when
promotions apply.
• If a promotion has already been applied to an order and that promotion excludes another
promotion, the excluded promotion cannot be re-included by any promotions that apply
later in the pricing process.
• Exclusion rules for individual promotions are evaluated in addition to any stacking rule
exclusions. See Manage promotions with stacking rules for more information.
To select promotions to exclude from the current promotion, follow these steps:
1. On a promotion’s details page, click Exclusion Rules.
2. Click the Edit button next to the Promotions to Exclude box.

12-23
 Chapter 12
Add a coupon code to a promotion

3. Select a promotion from the list. You can filter the list by typing or pasting some
text in the Promotions box.
The filter control matches letters or numbers that you type, wherever they appear
in the name or ID, not just at the beginning. Usually, as you type more characters,
there are fewer matches. When you see the item you want, select it.
The list contains the type of promotions you can exclude based on priority:
• Item promotions can exclude other item promotions, plus order and shipping
promotions
• Order promotions can exclude other order promotions, plus shipping
promotions.
• Shipping promotions can exclude only other shipping promotions.
4. Click Add Selected.
5. Click Done when you finish adding promotions to exclude.

Add a coupon code to a promotion

Coupons make promotions available only to shoppers who enter a valid coupon code
at checkout.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The administration interface lets you assign only a single coupon or coupon batch to
each promotion. However, you can use the Admin API to associate multiple
promotions with a coupon or coupon batch. See Assign and manage coupons for more
information.
You can create a single coupon that has one code or a batch of coupons that each has
a unique code all based on a prefix that you specify. If you add a coupon to a
promotion, shoppers must provide a valid coupon code to apply the promotion to their
order.
You cannot edit a coupon code after you create it but you can delete it and create a
new one. Coupon codes are case sensitive and must be unique across all promotions,
even promotions that are not enabled.
On the Marketing page, you can create one coupon or batch per promotion. However,
you can use the Admin API to associate more than one coupon or batch with a
promotion. If a promotion has multiple coupons or coupon batches associated with it,
the promotion’s Availability page displays the number of coupons and coupon batches,
plus the ID for the first of each. See Assign and manage coupons for more information.
Important: If you delete all a promotion’s coupons, Commerce automatically disables
the promotion until you associate it with at least one coupon or coupon batch and then
re-enable it by selecting the Enabled checkbox on the promotion’s details page. See
Enable and disable promotions for more information.
By default, any shopper who has a valid coupon code can use it, but you can restrict
coupon usage in the following ways:
• Limit the number of times a coupon code can be redeemed during the life of the
promotion. This limitation applies to the code itself, not to individual shoppers who
redeem it.
• Limit the number of times a shopper can apply a coupon code to an order.

12-24
 Chapter 12
Add a coupon code to a promotion

• Specify that a coupon code can be used only by registered shoppers. (By default, a
coupon can also be used by anonymous shoppers.) You can also limit the number of
orders to which a registered shopper can apply the code.
To create a coupon or batch, follow these steps:
1. On the Marketing page, click the promotion you want to associate with a coupon code.
2. On the promotion's Availability tab, click Create Coupon.
3. Create a single coupon or a batch of coupon codes:
Select Single Code to create a coupon with a one code, then enter the coupon code.
(Each coupon code must be unique; you cannot use the same one for multiple
promotions.)
Select Batch of Codes to create a batch of unique coupon codes, then enter a prefix for
the codes. (Each prefix must be unique; you cannot use the same one for multiple
promotions.) Enter the number of coupon codes to create.
4. Enter the number of times a code can be used or select Unlimited to create a coupon or
batch that has unlimited use during the time that the promotion is enabled.
5. Under Number of Uses Per Order, enter the number of times a shopper can redeem
this promotion on a single order or select Unlimited to allow unlimited uses on a single
order.
6. Click Create.
Commerce creates the coupon or batch and displays options that let you further limit its
use:
7. Select Registered Shoppers Only to restrict coupon redemption to registered shoppers.
(See Understand the different types of shopper to learn the difference between registered
and anonymous shoppers.)
8. Specify how many times (that is, on how many orders) a registered shopper can redeem
the coupon. Under Grant to a registered shopper more than once, select No to limit
the coupon to a single redemption or select Yes to let a registered shopper redeem the
coupon more than once. If you select Yes, enter the number of valid orders on which a
shopper can redeem the coupon.
When you grant a coupon to a registered shopper more than once, Commerce adds a
copy of the promotion to the the shopper's profile for every grant.
Each grant applies to one order, not to one discount. If you entered a number greater
than one for Number of Uses Per Order to allow the promotion to discount a single
order multiple times, using the promotion on that order still counts as one grant.

View and export coupon batches

You can view information about coupons within a coupon batch by exporting the batch to
CSV format. The exported spreadsheet includes each code in the batch, the coupon’s ID, the
prefix you specified for the codes, the maximum number of uses, and the promotion to which
the coupon is assigned.
To view and export a coupon batch, follow these steps:
1. On the Promotions page, click the promotion whose coupon batch you want to export.
2. On the promotion’s Availability tab, the Export button next to the coupon code.
3. Follow your Web browser prompts to open or save the file.

12-25
 Chapter 12
Manage promotions with stacking rules

Manage promotions with stacking rules

Stacking rules prevent shoppers from taking advantage of unintended synergy among
your promotions by combining certain offers.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This section includes the following topics:

• Understand stacking rules
• Create stacking rules

Understand stacking rules

Each stacking rule includes a number of promotions that you want to treat as a group.
Rules are intended to prevent simple combination strategies, for example to keep
customers from combining buy one get one offers with gift-with-purchase offers. In this
example, you could add all your buy one get one promotions to one stacking rule and
all your gift-with-purchase promotions to another. Then you specify that the buy one
get one stacking rule cannot be combined with the gift-with-purchase rule.
Stacking rules have the following behavior:
• Each promotion can be associated with only one stacking rule. If a promotion is
already part of a stacking rule and you add it to another, Commerce automatically
removes it from the first rule.
• Within a stacking rule, promotions are applied in order, based on their priority. See
Understand promotions for more information about promotion priority.
• If an order qualifies for more than one promotion, and those promotions are in
mutually exclusive stacking rules, the promotion with the highest priority is applied,
and all other promotions the order qualifies for are skipped.
• In addition to stacking rules, each promotion’s exclusion rules allow you to define
individual promotions that cannot be combined with it. Exclusion rules override
stacking rules. For example, if Promotion A excludes Promotion B, those
promotions cannot be combined, even if they are in the same stacking rule or
stacking rules that combine with each other. See Exclude promotions for more
information.
• If a promotion has already been applied to an order and that promotion excludes
another promotion, the excluded promotion cannot be re-included by any
promotions that apply later in the pricing process.

Create stacking rules

To create a new stacking rule, follow these steps:
1. On the Promotions page, click Stacking Rules.
2. Click the New Rule button to display the details page for the rule.
3. Enter a name for the new rule.
4. Specify promotions to add to the rule.
• Click Edit and select promotions to add to the rule. You can filter the list by
typing or pasting some text in the Promotions box.

12-26
 Chapter 12
Manage upsell messages

The filter control matches letters or numbers that you type, wherever they appear in
the name or ID, not just at the beginning. Usually, as you type more characters, there
are fewer matches. When you see the item you want, select it.
• Click Add Selected.
• Click Done when you finish adding promotions to the rule.
5. Specify the maximum number of promotions that can be applied to an order from this
rule. The default value is Unlimited.
If you specify a maximum number of promotions, Commerce evaluates the rule’s
promotions in order, based on their priority. See Understand promotions for more
information about promotion priority.
6. Click the Create button.

Manage upsell messages

Upsell messages let you alert shoppers to promotions and show shoppers when they are
close to fulfilling a promotion’s buy or spend condition.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

For example, suppose your store is running a Gift with Item Purchase promotion that offers a
free team scarf with every two jerseys from the same team shop. When a shopper begins
checkout with a cart that contains one jersey, the cart page could display the following
message: Wait! Buy one more jersey to get a free scarf! When the shopper adds a second
jersey to the cart, the free gift is added and the message could change to: Enjoy your free
scarf!
This section describes upsell messages and explains how to create them in the
administration interface. To learn how to customize widgets and elements so you can display
the messages on your storefront, see Set up promotion upsell messages. This section
includes the following topics:
• Understand upsell messages
• Understand tags
• Create upsell messages
• Localize upsell messages
• Delete upsell messages

Understand upsell messages

Each promotion can have one set of upsell messages. Each set of upsell messages can
contain one each of the following three types of messages:
• Not Qualified: This is a global message that alerts shoppers to a promotion. For example,
Free US Flat Rate Shipping On Orders Over $75.
• Partially Qualified: This message appears when a shopper has partially qualified for the
promotion. For example, Spend Just $10 More For Free Shipping!
• Success: This message appears when the shopper has qualified for the promotion. For
example, Congratulations! Your Order Ships For Free!
Important: If a promotion requires a coupon code, shoppers will not see any of its upsell
messages, including the Not Qualified message, until they enter the coupon code in the

12-27
 Chapter 12
Manage upsell messages

shopping cart. See Add a coupon code to a promotion for more information about
promotions that require coupons.
This section describes each type of upsell message you can create in the
administration interface.
Not Qualified message
The Not Qualified message alerts shoppers to a promotion. You can show the
message to all shoppers who can access the promotion, even if they have not yet
started to qualify for it. Display a Not Qualified message where it can be easily seen by
shoppers, for example, in a banner at the top of each page on your storefront.
Partially Qualified message
The Partially Qualified message appears when a shopper begins to qualify for the
promotion. Partially Qualified messages are triggered by a value you specify, often
called a closeness qualifier. For example, suppose a promotion offers free shipping
when a shopper spends $75 anywhere in the store and you want to display the
Partially Qualified message when a shopper places anything in their cart. Set this
value to 1 to display the message when any item that costs $1 or more is added to the
cart. To display the message only when a shopper needs to spend $25 or less to
qualify for the promotion, set the value to 50.
Partially Qualified messages include variables that represent values to display in the
message. When the message is displayed on the storefront, Commerce replaces the
variables with the actual values that represent a shopper’s cart and its qualification for
the promotion.
The following table describes each variable and lists the promotion templates for which
it is available.

Variable Description Promotion Templates

{{AmountSpent}} {{AmountSpent}} specifies the Spend Y Get Gift with
{{AmountStillNeeded}} shopper’s current qualifying Purchase
spend amount. Spend Y in X Get Item
{{AmountStillNeeded}} Discount
specifies the minimum spend Spend Y in X Get Order
amount to qualify for the Discount
promotion minus the shopper’s
Spend Y for Order Discount
current qualifying spend
amount. Spend Y Get Shipping
Discount
Note: Commerce
automatically adds the Spend Y in X Shipping
appropriate currency symbol Discount
and separator to the amounts
specified by these variables.
{{QuantityBought}} {{QuantityBought}} specifies Buy One Get One
{{QuantityStillNeeded}} the number of qualifying items Gift With Item Purchase
in the shopper’s cart.
Buy X Get Order Discount
{{QuantityStillNeeded}
Buy X Get Shipping Discount
specifies the minimum number
of items to qualify for the
promotion minus the number
of qualifying items in the
shopper’s cart.

12-28
 Chapter 12
Manage upsell messages

For promotions whose Partially Qualified messages use the {{QuantityBought}} and
{{QuantityStillNeeded}} variables, Commerce does not change the message text based on
singular or plural quantities. For example, suppose a promotion offers 10% off with the
purchase of three toys and the message displays when a shopper adds one toy to the cart.
The message “Buy 2 more toys to get 10% off!” makes sense, but when the shopper adds a
second toy to the cart, the message changes to “Buy 1 more toys to get 10% off!” A better
message in this instance is one that accommodates one item or multiple items. For example,
“Toy Sale! Buy {{QuantityStillNeeded}} more to get 10% off.”
You cannot create a Partially Qualified message for the following types of promotions,
because they do not require buy or spend conditions:
• Get Item Discount
• Get Shipping Discount
• Gift with Item Purchase if the buy condition is set to Give Gift with Any Order.
Success message
The Success message lets a shopper know they have successfully qualified for the
promotion. The success message is displayed when the shopper’s cart qualifies for the
promotion.

Understand tags
Tags are strings that establish a relationship between upsell messages and the widgets that
will display them on your storefront. You add tags to upsell messages when you create them
on a promotion’s Messaging tab. Then storefront developers add the tags to widgets and that
will display the messages to shoppers.
You can assign one or more tags to a single upsell message. You can create and save a
message without adding tags to it, but a message with no tags cannot be displayed on your
storefront.
Once you create a tag, it is available to all upsell messages in all promotions. You can assign
the same tag to more than one message, including messages for different promotions. This
can be useful if, you create similar promotions for different audiences or different sites. For
example, you can assign the tag home to Not Qualified messages you want to display on
your store's Home page to alert shoppers to promotions. Similarly, you can assign the tag
cart to Partially Qualified messages so shoppers can see how close they are to qualifying
when they go to check out.
If you assign the same tag to all three of a promotion’s upsell messages, the messages
replace each other on the storefront wherever the tag displays them. For example, suppose
you assign the tag FreeShip to all three upsell messages for a promotion that offers free
shipping to any shopper who spends $150 on a single order. You configure the Partially
Qualified message so that it appears when the value of a shopper’s cart is at least $10. You
add the FreeShip tag to a banner on your storefront. When a shopper arrives at the site, they
see the Not Qualified message (FREE U.S. Flat Rate shipping when you spend $150). in the
banner. When the shopper places an item priced at $49.99 in the cart, the Not Qualified
message is replaced by the Partially Qualified message (Only $50.01 away from FREE U.S.
Flat Rate shipping!). When the shopper places another item, priced at $75 in the cart, the
Partially Qualified message is replaced by the Success message (Your order qualifies for
FREE U.S. Flat Rate shipping!). If the shopper removes one of the items from the cart, the
Success message is once again replaced by the Partially Qualified message.
For more information about how Commerce determines which messages to display for a
specific tag, see Set up promotion upsell messages.

12-29
 Chapter 12
Manage upsell messages

Keep the following in mind when you create tags:

• Tags are case sensitive; for example, Commerce treats banner and BANNER as
two different tags.
• Do not use the following characters in tags: < > { } {{ }} “
• Tags must be published before widgets can use them on your storefront. See
Publish Changes for more information.
You cannot delete tags in the administration interface. You must use the Admin API
messageTags endpoints to delete tags. See Set up promotion upsell messages for
more information.

Create upsell messages

This section describes how to create upsell messages and tags in the administration
interface. To learn how to customize widgets and elements so you can display the
messages on your storefront, see Set up promotion upsell messages.
You create the messages on a promotion’s details page, with an HTML editor called
CKEditor. You can write, update, and apply rich-text formatting to upsell messages.
To create upsell messages for a promotion:
1. On a promotion’s details page, click Messaging.
2. Enter and format the text for each message type.
3. Create or select tags to add to each message.
• Click the Tag box and begin typing to display a list of existing tags. You can
filter the list by typing or pasting more text in the box.
• To add a tag from the list, select it and press Enter.
• To add a new tag, continue typing the text for the tag and then press Enter.
4. For Partially Qualified messages, enter an amount that will trigger display of the
message.
5. Click Create to save the message.
6. Publish your changes.
If you edit a promotion, check its upsell messages to see if they need to be updated.
Changing a promotion’s condition or offer without changing its upsell messages can
cause unexpected results. For example, suppose a promotion offers free shipping
when a shopper spends $100 and its Partially Qualified message is configured to
appear when the shopper has spent $60. If you change the promotion’s condition to
offer free shipping when the shopper spends $50, the unchanged Partially Qualified
message might never appear, and when it does, it will present incorrect information.

Localize upsell messages

You can translate the text of Not Qualified, Partially Qualified, and Success messages
the same way you translate other text that appears on your storefront. (See Translate
store text for more information.) You cannot translate tags or the variables you use
with Partially Qualified messages.
Commerce does not convert minimum spend amounts in promotions and upsell
messages across different currencies your store supports. If your store supports

12-30
 Chapter 12
Manage upsell messages

multiple currencies, create a separate version of each minimum-spend promotion for each
currency. See Understand currency-specific promotions for more information.

Delete upsell messages

You can delete one or more upsell messages from a promotion. Deleting a promotion also
deletes its upsell messages. Deleting upsell messages does not delete any tags assigned to
them. You must use the Admin API to delete tags. See Set up promotion upsell messages.
for more information about deleting tags.
To delete an upsell message from a promotion:
1. On a promotion’s details page, click Messaging.
2. Click the Delete icon for the message you want to delete.
3. Confirm that you want to delete the message.
4. Publish your changes.

12-31
13
Define Audiences
Defining an audience allows you to target content to certain groups of shoppers. You define
an audience by creating a set of rules based on attributes of the shopper profile. The
audience can then be used by other tools for personalizing the shopper’s experience.
This section describes how to work with audiences on the Marketing page.

Understand audience definitions

An audience represents a segment of the shoppers that visit your store.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You define these audiences in the Audience window by creating rules that include or exclude
shoppers according to their profile attributes. For example, you could create an audience
called Student Females Outside Texas that includes female shoppers that have an .edu email
address, but excludes people living in Texas. The rules that define this audience might look
something like this:
Include these people:
• People whose Gender is Female
• and whose Email Address ends with .edu
• and whose Shipping Address State is not Texas
After you define this audience, you can deliver personalized content to shoppers who match
Student Females Outside Texas criteria.
To comply with the European Union General Data Protection Regulation (GDPR), a shopper
may be required to provide consent to have their shopper profile data used for
personalization. If a registered shopper is required to provide GDPR profile personalization
consent (if the GDPR profile personalization site setting is set to true for that site) and does
not, the non-consenting shopper is not recognized as a member of any audience that uses
shopper profile data even though they may meet the audience rules criteria. For information
on GDPR consent and profile-based personalization, see Manage the Use of Personal Data.

Parts of an audience definition

An audience definition is composed of the following parts:
• Display Name This is the name that appears in administration interfaces.
• ID This ID is automatically generated from the display name that you provide. You can
override the generated one if you want and create your own ID.
• Rules This set of rules consist of one or more rules that you define to include or exclude
shoppers.

13-1
 Chapter 13
Understand audience definitions

• Enabled/Disabled This determines if an audience can be used in production. No

shopper is considered a member of a disabled audience even if the audience is in
use by a content variation slot, a promotion, or an experiment.
• Visitor Type This determines if an audience includes only anonymous shoppers,
only registered shoppers or all shoppers (registered and anonymous)
• Match All Rules/Match Any Rules toggle. Whether a shopper must match all of
the audience rules to be considered a member of the audience, or whether
matching at least one of the rules is sufficient.
• Capture reporting data for this audience This determines whether membership
in this audience should be evaluated and recorded for reporting purposes, when a
shopper submits an order.

Attribute categories
Commerce groups attributes into categories.

Attribute category Description

Account Attributes of shoppers who have logged in using
contact credentials that have been defined as part
of a business account. This category only appears if
account-based shopping has been enabled in your
environment. Contact your Oracle account manager
for more details on how to activate this functionality.
Revenue The revenue information of shoppers, including their
recent purchases, the frequency of their purchase
and the monetary value of both individual and all
purchases.
Engagement The frequency and number of visits made to the site
by the shopper.
Geolocation The geographical location of the shopper, which are
attributes associated with the shopper’s current
location.
Entry Page The Entry Page is a landing page on the Oracle
Commerce site or a Referring site. It enables
merchants to automatically apply promotions for
shoppers visiting from a particular referring site, and
provide a different experience for segments of
shoppers landing directly on a particular page of the
website.
Entry Page Query Parameter Entry page attributes that can be used in rules to
more effectively personalize site experiences. For
most merchants the majority of site visits start at
another place, for example, another site, a Google
search leading to a shopper clicking on a Pay Per
Click (PPC) ad, a marketing email or a Facebook
ad. Marketers can use UTM parameters (used by
Google Analytics and other systems) or custom
query parameters to pass context for a site visit
from an external site, a PPC ad, a marketing email,
or another source. You can define your own custom
query parameters if you use systems other than
Google Analytics or have more complex needs.

13-2
 Chapter 13
Understand audience definitions

Attribute category Description

Browsing Shopper browsing behavior, that is, views of
products or collections, in the current visit. Tracking
shopper browsing behavior enables merchants to
design appropriate site experiences for those
shoppers. For example, merchants can promote a
product or a collection of products to regular
viewers of the product or collection of products, or
suggest a product to a shopper before checkout.
Device Attributes of the device (such as a computer, tablet,
or phone) the shopper is using to access the site.
Shopper Profile Attributes of individual registered shoppers who
have logged in to a personal account
Audience Audience attributes are existing audiences that can
be used in rules to categorize shoppers who are
members of existing audiences. This category only
appears as a choice in the interface after you have
defined at least one audience.

Attributes available in all categories

The attributes listed in the following table are in both the shopper profile and account
categories. In the shopper profile category, these attributes belong to the individual shopper.
In the account category, these attributes belong to the account.

Attribute Description
Shipping Address City City for the shopper's default shipping address.
Shipping Address State State for the shopper's default shipping address.
Shipping Address Postal Code Postal or zip code for the shopper's default shipping
address.
Shipping Address Country Country for the shopper's default shipping address.
Registration date The date that the shopper’s profile was created.

Attributes only available in the engagement category

The following attributes are available only in the engagement category.

Attribute Description
First visit date The date of the shopper’s first visit to a site. For the site
on which the shopper registered, the first visit date is
the same as the registration date.
Note: If a shopper’s registration date is before the
current release, the first visit date is the shopper’s first
visit after the shopper upgrades to the current release.
Previous visit date For a currently logged in shopper, the date of the visit
before the current one. For a shopper who is not logged
in, the date of the visit before the last one.
Note: Another attribute, Last visit date, is the date of the
current visit for a currently logged in shopper, or the
date of the last visit for a shopper who is not logged in.

13-3
 Chapter 13
Understand audience definitions

Attribute Description
Number of Visits The anonymous or registered shopper’s number of
visits to a site. The number includes the current visit.
For registered users who existed before the 18D
release, the number of visits is set to the number of
orders made. For anonymous shoppers who existed
before 18D, the default number of visits is set to 2.

Attributes only available in the revenue category

The following are attributes that are available in the revenue category.
The following attributes are available for both logged-in shoppers and anonymous
shoppers: First Purchase Date, Last Purchase Date, Last Purchase Amount, Lifetime
Average Order Value, Lifetime Spend, and Number of orders. For additional
information on these attributes, refer to Qualifying orders.

Attribute Description Site-

Specific
First purchase date The date of the shopper’s first order. Order Yes
must be a qualifying order.
Last purchase date The date of the shopper’s last order. Order Yes
must be a qualifying order.
Last purchase amount Total of the shopper’s last order, including tax Yes
and shipping. Order must be a qualifying order.
Lifetime average order value Average of the shopper’s order totals, Yes
including tax and shipping. Orders must be
qualifying orders.
Lifetime spend Grand total, including tax and shipping, of the Yes
shopper’s order totals. Orders must be
qualifying orders.
Number of orders Number of orders for this shopper. Orders Yes
must be qualifying orders.

Attributes only available in the shopper profile category

The attributes listed in the following table are only available in the shopper profile
category.

Attribute Description Site-specific (if multiple

sites exist)
Date of Birth The shopper’s date of birth No
Email address The shopper’s email address No
Receive email A shopper can opt in/opt out of No
email notifications
Gender The shopper’s gender. You No
can only use this attribute in a
rule if you are collecting
gender information in a
custom widget.

13-4
 Chapter 13
Understand audience definitions

Attribute Description Site-specific (if multiple

sites exist)
Currency The currency used when Yes
making orders. Mandatory for
these properties:
Lifetime average order value
Lifetime spend
Last purchase amount
When the user creates a rule
with a currency property, the
currency is initially set to the
currency of the default price
list group of the default site.

Note: If you use different default currencies on different sites, and you want to create
audiences based on Lifetime Spend or Lifetime Average Order Value, define an audience for
each site (currency). For example, you can define an audience “High Spenders USD” with the
rule “Lifetime Spend > 1000” and another audience “High Spenders euro” with the rule
“Lifetime Spend > 940”.
Qualifying orders
A qualifying order must meet the following conditions.
• The order uses the shopper’s lifetime currency. The shopper lifetime currency is set to
the currency of the first order made in a monetary currency. If a shopper subsequently
makes an order in a different monetary currency, the value of that order will not be
included in monetary lifetime order values.
Note that if a site’s default currency is monetary, and shoppers can use loyalty points to
pay for some or all of an order, then Lifetime spend and Lifetime average order value
attributes reflect only the monetary portion of the total - even if this total consists only of
tax and shipping.
• The order is in one of the following states:
– SUBMITTED
The order has completed the purchase process and has been submitted to the order
management system.
– PROCESSING
The order is being processed by the order management system.
– NO_PENDING_ACTION
The order has been fulfilled, and processing of the order is complete.
• Each payment associated with the order is in one of the following payment states:
– AUTHORIZED
The payment has been authorized and can be debited.
– SETTLED
The payment has been debited successfully.
– PAYMENT_DEFERRED
Only applicable for invoice and PO orders where an invoice is sent to the shopper.
For more information on order and payment states, see Manage Orders.

13-5
 Chapter 13
Understand audience definitions

Attributes only available in the account category

The attributes listed in the following table are only available in the account category.

Attribute Description
Customer Type The type of industry to which this customer
belongs.
Name Name of the account
Type The type of organization, for example,
department or division. This cannot be a null
value.
Billing Address City City where shopper’s bills are sent.
Billing Address State State where shopper’s bills are sent.
Billing Address Postal Code Postal code or zip code where shopper’s bills
are sent.
Billing Address Country Country where shopper’s bills are sent.

Attributes only available in the geolocation category

The attributes listed in the following table are available in the geolocation category.

Attribute Description
Latitude Truncated latitude, that is, the integer portion
plus first two decimal points. For example,
North of 36 degrees North is represented by
the following:
Attribute: Latitude, Operator: North Of, Value:
36.00
Longitude Truncated longitude, that is, the integer portion
plus first two decimal points. For example, US
states between 165 degrees West and 105
degrees West is represented by the following:
Attribute: Longitude, Operator: Westward
between,
Start Value: 165.00 West, End Value: 105.00
West
Place A place can be a country, region or city. Start
entering the name of the place, then use
typeahead to select the right value.
Note: Region differ in granularity by country.
For example, in the United States, regions are
equivalent to States; but in the United
Kingdom they are equivalent to England,
Wales and other regions.
Only cities worldwide with a population of
more than 100,000 people are included.
Timezone Time zone is formatted as offset from GMT
plus time zone and geographic area. For
example, GMT-5 EST Eastern Standard Time.

Attributes only available in the entry page category

The attributes listed in the following table are available in the entry page category.

13-6
 Chapter 13
Understand audience definitions

Attribute Description
Landing page URL This can be used to present a personalized
experience to shoppers landing on a particular set
of landing pages on the site. For example, landing
page URL contains holiday.
Referring site If a customer reaches a Commerce site from a
link on a third party site, that site is the referring
site.
Note: Audience rules based on the referring site
URL do not function correctly for shoppers
browsing in Mozilla Firefox using private browsing
mode.

Attributes only available in the entry page query parameters category

The attributes listed in the following table are available in the entry page query parameter
category. The data type for these attributes is a string property that can have multiple values
at a time. In addition to the available UTM parameters, you can also create custom query
parameters and set a value for each parameter, if you use systems other than Google
Analytics or have more complex needs.

Attribute Description
utm_campaign Campaign name, which is commonly used by
marketers to uniquely identify a marketing
campaign.
utm_source Identifies where the traffic is coming from, for
example, email marketing, Pay Per Click (PPC),
social, organic search and third party sites.
source is typically something like Google,
Facebook or Twitter, or the name of an affiliate, ad
platform, or publisher. It’s used to indicate the
context the user was in when they clicked a link.
utm_term Indicates the paid keyword used. Term is often
used for paid search terms and keywords to
identify the audience at a finer grain than the
campaign, when you purchase multiple terms for
the same campaign.
utm_medium The advertising or marketing medium, for
example, email marketing, special offers, Pay Per
Click (PPC), social, or third party site. It can also
be used for the channel, for example, mobile, web,
or kiosk.
utm_content Content is often used with paid ads to represent
the content of the ad, or with click-throughs to
represent the content of the call to action (CTA)
that the user clicked.

Attributes only available in the browsing category

The attributes listed in the following table are available in the browsing category.

13-7
 Chapter 13
Understand audience definitions

Attribute Description
Device Type The type of device, for example, Mobile or
Non-Mobile.
Operating System The operating system of the device, for
example, Android or iOS.
Product Page An individual product.
Note: Viewing a list of products within
collection pages or clicking the Quick View of a
product does not qualify as a product page
view.
Product Name Products whose names contain a localized
string, for example, Vitamin C.
Product Criteria Any combination of product brand, collection
and product type. You do not need to specify a
value for every field.
Note: Number of views is being defined as
unique views of products. Viewing the same
product multiple times in a visit counts as one
view.
Collection Page An individual collection, for example, the
Vitamins collection.
Collection Name Collections whose names contain a localized
string.
Note: Number of views is being defined as
unique views of collections. Viewing the same
collection multiple times in a visit counts as
one view.

Types of behavioral audience rules

You can define three types of behavioral audience rules:
• Precise attributes match views of individual products or collections. Product Page
and Collection Page are precise attributes. For example, a rule that includes
shoppers who viewed the product page for NH Ultra Vitamin C 100 tablets two or
more times in the current visit:
Attribute: Product Page, Operator: viewed, Product: NH Ultra Vitamin C 100
tablets, Number of Views: >= 2
• Broad attributes match views of products or collections where the name matches
a specified string. Product Name and Collection Name are broad attributes. For
example, a rule that includes shoppers who viewed at least three collections
whose name contain "Vitamin" three or more times in the current visit:
Attribute: Collection Name, Operator: viewed, Name: Vitamin, Number of Views:
>= 3
• Powerful attributes use product criteria to specify products which match any
combination of brand, collection and product type. Product Criteria is a powerful
attribute. For example, a rule that includes shoppers who viewed at least two
products whose brand is Ultra and in the Vitamin collection:
Attribute: Product Criteria, Operator: viewed, Brand: Ultra, Collection: Vitamins,
Number of Views: >= 2
The language picker

13-8
 Chapter 13
Understand audience definitions

The language picker is displayed on the Product Name, Collection Name and Product Criteria
attribute pages. The language picker contains a list of applicable store content languages (as
defined in Settings > Location). The default value is the store content language in use at the
time when the rule is created. Once you select a language, the value is used for the entire
session in the current visit. For example, if the selected language is English, the rule will
match the English name of the product to the string. If only one language is defined for store
content, the language string is displayed.

Use gender in rules for audiences

If you want to define an audience that uses the gender attribute in the rule, you must be sure
that your store includes a gender element that a shopper can use to provide gender data. You
can add this element by customizing a widget that is deployed in your store.
Gender is included as a property in the user view model which is available to all widgets. You
can add gender to a widget by updating the HTML in the widget’s template. For example,

<div class="form-group row">

<div class="controls col-md-12">
<label class="control-label inline" for="CC-userRegistration-
gender">Gender</label>
<select class="col-md-5 form-control" data-bind="value:gender">
<option value="" disabled selected>Select your gender</option>
<option value="male">Male</option>
<option value="female">Female</option>
<option value="unspecified">Unspecified</option>
</select>
</div>
</div>

For information about updating the HTML in a widget or stack, see Modify a component’s
code.

Use numbers in rules for audiences

If you want to define an audience that uses a numeric attribute in a rule, note the following:
• You can only enter one number in a value field. You cannot enter a list of numbers.
• The number cannot be less than zero.
• The Between operator is inclusive. For the rule to be a match, a value must be equal to
or between the low and high values.

Use dates in rules for audiences

If you want to define an audience that uses a date attribute in a rule, note that date values are
represented as a series of values for each date unit: year, month, and day. When a rule with a
date is evaluated, only the individual date unit that is specified is the unit that is changed.
The following example illustrates how rules with date properties are evaluated.
Let’s say that today’s date is May 5, 2017. This date can be expressed in these date units:

Year = 2017

Month =5

Day = 5

13-9
 Chapter 13
Understand audience definitions

In a rule with “More than 3 months ago”, “month” is the specified unit, so 3 is
subtracted from the month unit:

Year = 2017

Month = 2 (that is, 5-3)

Day = 5

Therefore, any date before February 5, 2017 evaluates as true.

Months have different numbers of days, so let’s look at another example, where this
difference can affect how your rule is evaluated. Let’s say that today is May 30, 2017.
In the same rule with “More than 3 months ago,” “month” is still the specified unit, so 3
is again subtracted from the month unit:

Year = 2017

Month = 2 (that is, 5-3)

Day = 30

A date of February 30, 2017 does not exist, but the rule can still evaluate dates. In this
case all days in February would evaluate as true.
Weeks and date attributes
Remember that date values are represented as a series of values for each date unit:
year, month, and day. There is no week unit. Weeks are the equivalent of seven days.
For example, “more than 3 weeks ago,” is the same as “more than 21 days ago.”
Timestamps and the date attribute
Even though rules do not include timestamps in any of the available rule operators for
dates, timestamps do affect how a rule is evaluated.
For example, let’s say that the rule for an audience is “Last Purchase Date is Less
than 1 day ago”. The current date and time is March 15, 2017, 12:00 PM GMT. The
rule evaluation will calculate a date exactly 1 day from the current date and time, which
will be March 14, 2017, 12:00 PM GMT. If Last Purchase Date is equal to March 14,
2017, 11:00 AM GMT, the rule evaluates as true. If Last Purchase Date is equal to
March 14, 2017, 1:00 PM GMT, the rule evaluates as false.
Note that all time is evaluated in GMT.
Between operator in rules with date attributes
Just like with number attributes, when a date attribute uses a Between operator, the
operator is inclusive. For the rule to be a match, a value must be between or equal to
one of the low and high date values.

Custom properties
You can create custom properties using the Admin API and include them as attributes
in your rules when you define an audience. Custom properties are available in shopper
profile and account categories, and can be created as custom string property or
custom property for rich text fragment (custom rich text property. For example,
partnerCustomerData contains the value: partner=AirPortugal ). The custom
property:
• Must be a string, Boolean, date, numeric, or rich text data type.

13-10
 Chapter 13
Understand audience definitions

• Must have audienceVisibility set to all for shopper profile properties, and to b2b for
account properties.
• Can have appropriate value up to 1,000 characters if it's a custom rich text property.
• Is not used in the rules for calculating audience size if it's a custom rich text property.
The audienceVisibility attribute determines whether or not a property appears as a choice
in the Attributes field of the audience interface.
• For shopper profile properties, see Manage Shopper Profiles.
• For account properties, see Manage an Account-based Storefront.

Estimated audience size

The Estimated audience size under Rules displays an estimate of how many users are in a
specific audience. It returns the number of registered shoppers that match any or all of the
rules depending on the current value of the Rule Matching selection list. Anonymous
shoppers are not included in the estimates. In a multiple-site environment, the audience size
is estimated for the default site. You can select an alternative site to see the impact on
estimates.
Each successive rule shows the new size of the audience with that rule added.
• For Match Any Rule, each successive rule adds just those shoppers who satisfy that rule
but did not satisfy any of the previous ones. The audience can only grow or stay the
same size as rules are added, and each new size shows that growth.
• For Match All Rules, each successive rule adds a new restriction to the audience,
removing shoppers who satisfied the previous rules but do not satisfy the new one. The
audience can only decrease or stay the same size as rules are added, and each new size
shows that decrease.
Changing the order of the rules affects the size estimates per rule on the Audiences page, but
does not affect the audience size and shoppers evaluated as being members of the
audience. To see the accurate size of a rule on the Audiences page, create an audience with
only that rule.
If the GDPR profile personalization site setting is set to true for that site, audience size
estimate takes GDPR into consideration for the numerator only in calculations. For example,
among 100 shoppers, 40 have provided GDPR consent for that site, and 25 are in the
audience. Commerce displays:
• Audience size estimate of 25 shoppers for the site
• Audience size estimate of 25 shoppers for the site
Percentage value of shoppers as 25% (based on 25/100)
For information on GDPR consent and profile-based personalization, see Understand
consent and profile-based personalization in Manage the Use of Personal Data.

Create audiences for anniversaries

You can define audiences that include people for whom the anniversary of an event is
upcoming. The event can be any date-valued profile property, such as a birthday, the
anniversary of their first purchase, or the anniversary of their enrollment in a loyalty program.
You can identify visitors for whom the anniversary of an event occurs today, during the
current week, during the current month, or within a specified number of days from now.

13-11
 Chapter 13
View the list of audiences

View the list of audiences

The Audiences page displays a list of all the audiences that have been defined for
your store. You can view the name, description and usage information of each
audience. You can sort and filter the list.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Click the Marketing icon and then clickAudiences. You must be assigned the Admin
or Marketing role. Each audience entry displays the following information:
• Audience Name - short, descriptive display name that identifies the audience
• Description - longer description that explains the use or details of the audience
• Audience Usage – the users and the number of consumers of the audience
The list displays all audiences by default. The All Audiences view includes both
enabled and disabled audiences and regardless of its inclusion in reporting (a line
chart icon next to an audience indicates the audience is used in reporting). An
audience does not need to be published to appear in the list. You can change this view
by clicking All Audiences and selecting another view:
• Enabled Audiences includes only audiences that are available for targeting.
• Disabled Audiences includes audiences that are not available for targeting
content.
• Audiences Used in Reports includes audiences for which membership is
evaluated and recorded for reporting purposes, when a shopper submits an order.
The list can be sorted by clicking the Audience Name or Description column labels.
You can filter the list by starting to type an audience name or description in the Filter
list box. Sorting or filtering always resets your view of the list to the first page.

Create an audience
You can create a new audience on the Audiences page.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Follow these instructions to create an audience.

1. On the Marketing page, click Audiences.
2. Click New Audience.
3. In the Audience Display Name field, enter a unique short descriptive name of no
more than 50 characters that describes the audience. This name displays in the
administration interfaces.
Note: You cannot reuse the name of a deleted audience.
For example, if you are targeting female students that are not in Texas, you can
enter Student Females outside Texas.
After you finish typing and move to another field, the Audience ID field
automatically fills with an ID generated from the Audience Display Name.

13-12
 Chapter 13
Create an audience

Commerce uses this ID internally. This ID is regenerated whenever you update the
Audience Display Name field.
4. (Optional) Edit the automatically generated ID in the Audience ID field. You can edit an
ID until you click Create.
An ID can only contain alphanumeric characters. It cannot contain spaces, special
characters, or non-Latin characters.
5. (Optional) In the Audience Description field, enter a description that helps you to identify
the audience in the administration interface.
The description should help you distinguish this audience from others, especially if you
have exclusions. For example, “Female students and educators with edu addresses. This
audience excludes shipping addresses in Texas.
6. (Optional) If you do not want to enable the audience right away, deselect Audience
Enabled.
For example, you might want to disable an audience if you are creating a seasonal
audience, and that season has not started yet.
7. (Optional) If you want to evaluate membership in this audience and record it for reporting
purposes when an order is placed, select Capture reporting data for this audience.
If you have defined a large number of audiences, evaluating audience membership for all
of them may adversely affect performance. You can use this check box to restrict the set
of audiences for which membership is evaluated for reporting purposes.
8. In the Visitor Type field, select:
All shoppers – Both registered and non-registered shoppers.
Anonymous shoppers – Shopper who have not registered as a user for the site.
Registered shoppers – Shopper who have registered as a user for the site.
9. In the Rule Matching field, select:
Match Any Rule – A shopper must match at least one rule in order to be a member of
this audience.
Match All Rules - A shopper must match all rules in order to be a member of this
audience.
10. Click New Rule.

11. Select a category. See Attribute categories for more information.

12. Select the attribute, operator, and value you want to use. See these sections for
descriptions of the available attributes:
• Attributes available in all categories
• Attributes only available in the shopper profile category
• Attributes only available in the account category
If you selected Audience as a category in the previous step, then the Attribute field
automatically fills with the Membership attribute and you only have to set an operator and
values, that is, one or more audiences.
The selections in the Operator and Values drop-down lists change depending on the
attribute that you select. If the attribute has a limited set of values, the Value list includes
all of your possible choices. If the attribute has an unlimited number of values, you can
type a unique value directly into the list.

13-13
 Chapter 13
Update an audience

13. Click Done.

14. (Optional) If you have more rules to add, click New Rule.

An audience can have a maximum of 100 rules.

15. When you have finished adding rules, click Create.

The audience is immediately available for use in personalization. The audience is

not available in a production environment until it has been published.

Update an audience
You can update an audience by changing the display name or description, or by
adding, editing, or removing rules. You cannot change an audience ID.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

To update an audience, follow these steps:

1. On the Marketing page, click Audiences.
2. (Optional) Change the view by clicking All Audiences and selecting another view.
3. Click the audience that you want to update.
4. Edit the Audience Name or Audience Description fields. The Audience ID field
is read-only.
5. Add a rule by clicking New Rule just like you do when you initially create an
audience. See Create an audience.
An audience can have a maximum of 100 rules.
6. Edit a rule by clicking Edit next to the rule that you want to edit. Before you begin
making changes, note the following.
• If you change the Category, then the Attribute field is reset for attributes that
are appropriate for that category. The rest of the rule is removed.
If you changed the Category by mistake, cancel the edit to avoid having to
enter the attributes again.
• If you change the Attribute, then the Operator field is reset for operators that
are appropriate for that attribute and the Value field is cleared.
Click Done when you are finished.
7. Click Save.
Changes to the audience name and description take effect for use in the audience
definition interface. Rule changes do not go live until you publish them. See Publish
Changes.

Copy an existing audience

Creating a new audience based on an existing one lets you easily create a number of
similar audiences and lets you reuse audiences that successfully met your needs in
the past.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

13-14
 Chapter 13
Disable an audience

When you copy an existing audience, the following values are automatically copied to the
new audience:
• Audience Display Name
By default, this value will be set to the name of the audience that was copied, followed by
(Copy). For example, New Students (Copy).
• Audience Description
• Rules
When you copy an existing audience, the following values are not copied to the new
audience:
• Audience ID
A new audience ID is generated from the new audience display name. For example, a
display name of New Students (Copy) generates an ID of NewStudentsCopy.
• Enabled status
When you copy an audience, the new audience is automatically enabled even if the
source audience was not enabled.
To copy an existing audience, follow these steps:
1. On the Marketing page, click Audiences.
2. Click the row of the audience to copy and then click Copy.
Click anywhere in the row except on the link that is the audience name. Clicking that link
opens the existing audience.
3. Edit the Audience Display Name.
After you finish editing and move to another field, the Audience ID automatically fills with
an ID generated from the Audience Display Name.
4. (Optional) Edit the automatically generated ID in the Audience ID field. You can edit an
ID until you click Create.
Just like when you create an audience, an ID can only contain alphanumeric characters.
It cannot contain spaces, special characters, or non-Latin characters.
5. Edit the Audience Description, Enabled Status, and any rules that you want to change for
the new audience.
6. Click Create and then click Save.

Disable an audience
You might want to disable an audience if for example it is an audience for a seasonal content
and that season has passed.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You can also disable an audience if you learn that you made a mistake in the audience
definition and you want to temporarily turn it off.
1. On the Marketing page, click Audiences.
2. (Optional) Change the view by clicking All Audiences and selecting another view.
3. Click the audience that you want to disable

13-15
 Chapter 13
Delete an audience

4. Deselect Audience Enabled.

Disabling the audience takes effect immediately in the audience definition interface.
The audience is not disabled in a production environment until you publish your
changes.

Delete an audience
If you delete an audience, it cannot be reinstated.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Any association that an audience has with targeted content is also removed when you
delete the audience. You cannot reuse the audience name or ID. If you want to reuse
an audience at another time, you should consider disabling the audience instead of
deleting it. See Disable an audience.
1. On the Marketing page, click Audiences.
2. Click the audience that you want to delete.
3. Click Delete.
4. Confirm the deletion.
When an audience is deleted, it no longer appears in the audience definition interface,
and no shopper will be considered a member of the audience. However, your site will
continue to function. You can delete an audience first and remove all uses of it later.
The audience is not deleted from your production environment until you publish your
changes.

View audience usage

On the Audience Usage page, you can see which slots, audiences and promotions are
using an audience so that you have a full understanding before making a change,
including deletion of an audience, which may have unintentional consequences.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You can also navigate to users of an audience directly from the Audience Usage page.
To view audience usage, follow these steps:
1. On the Marketing page, click Audiences.
2. Click the name of an existing audience then the Audience Usage tab.
You can see the name, type and description of users of that audience.
3. To navigate to a user of an audience, click the name of that user. For example, Fall
Student Promotion.

Add personalization to headless applications

You can configure headless applications, such as native OS apps or custom web
apps, to establish a visit context for each shopper by evaluating the shopper's
audience membership.

13-16
 Chapter 13
Add personalization to headless applications

This section applies to Storefront Classic only.

Audiences allow you to target content to certain groups of shoppers. You define an audience
by creating a set of rules based on attributes of the shopper profile. See Define Audiencesfor
information about audiences. Custom (that is, headless) applications call /ccstore/v1/
audienceContext endpoints to use existing audiences to personalize content.

Before you begin adding personalization to a headless application, make sure that the
following tasks are already complete:
• Use the Commerce administration interface to create audiences and set locales and site
settings.
• Use the /ccadmin/v1/profiles endpoint to create shopper profiles.
• Make sure the custom application can call the Commerce REST APIs.
• Make sure the custom application conforms to the Internet Engineering Task Force
(IETF) cookie spec RFC 6265. The application must be able to store cookies specified in
REST responses and send them back in its REST requests.

View audience membership

You can use the REST API to pass a set of candidate audience IDs as query string
parameters, and get a response that includes the subset of IDs (if any) that pertain to
audiences a shopper belongs to. The must contain one or more of the following to identify the
shopper:
• Access token returned by the /login endpoint if the shopper is logged in or the soft-login
cookie returned from the /login endpoint if the shopper logged in previously.
If the request does not include either of these, the shopper is considered anonymous.
• Visit and visitor ID headers.
• x-ccsite header that identifies the site.
For example:

GET
/ccstore/v1/audienceMembership?filter=audience123,audience234,audience345
Authorization: Bearer <access_token>

x-ccsite: siteUS
X-CCVisitId: <visit ID>
X-CCVisitorId: <visitor ID>
Cookie: SOFT_LOGIN=plM0UbcY.... <encrypted profile ID>

The following is an example of the response returned:

200 OK
{
"audienceMembership": ["audience234", "audience345"]
}

13-17
 Chapter 13
Add personalization to headless applications

Shopper Profile rules

The Shopper Profile category includes attributes of individual registered shoppers who
have logged in to a personal account. See Understand audience definitions for details
about the available Shopper Profile attributes.
In order to personalize based on these profile attributes, the shopper must have a
profile. Once a shopper has a registered profile, the custom application can log in the
shopper by using the ccstore/v1/login endpoint. This endpoint sets a persistent
cookie called SOFT_LOGIN that expires after 14 months. In order to personalize based
in profile attributes, the call to /audienceMembership must contain either the access
token or the SOFT_LOGIN cookie. Without either of these, the shopper is considered to
be anonymous.

Geolocation rules
The Geolocation category includes attributes that identify the current geographical
location of the shopper. See Understand audience definitions for details about the
available Geolocation attributes.
If the custom application sends its requests through a content delivery network, like
the storefront application does, then those requests, including the one to /
audienceMembeship, will include an additional header. For example:

X-Akamai-Edgescape:

georegion=263,country_code=US,region_code=MA,city=CAMBRIDGE,dma=506,pms
a=1120,areacode=617,county=MIDDLESEX,fips=25017,lat=42.3933,long=-71.13
33,timezone=EST,zip=02138-02142+02238-02239,continent=NA
,throughput=vhigh,asnum=21399

This header is all the /audienceMembership endpoint needs in order to determine

membership for Audiences with Geolocation rules. Otherwise, you must use the Store
API to communicate geolocation data to the storefront server. Issue a PUT request to
ccstore/v1/audienceContext/currentSession/geolocation/current. For example:

PUT
ccstore/v1/audienceContext/currentSession/geolocation/current
Authorization: Bearer <access_token>

X-CCVisitId: <visit ID>

{
"country_code": "US",
"region_code": "CA",
"city": "SANDIEGO",
"timezone": "(GMT+11:00)",
"latitude": -25.4
}

This request must include the X-CCVisitId header, which specifies the visit ID that is
unique to a user session. The storefront server uses the value of this header as the

13-18
 Chapter 13
Add personalization to headless applications

key to the cache where this data is being stored. The same visit ID must be sent in the /
audienceMembership call, even if the shopper is not currently logged in.

All the fields in the request are optional. The custom application sends only the fields used in
the audience rules required for personalization. There is one exception: If a city is used in a
place rule, country_code must be sent along with city to disambiguate the city. To find the
place fields for any city, region, or country, query the /ccadmin/v1/places endpoint.

Entry Page and Entry Page Query Parameter Rules

Entry Page and Entry Page Query Parameter attributes specify how the shopper arrived at
the storefront. These rules can be based on landing page URL, referring site, or a variety of
default UTM and custom query string parameters. See Understand audience definitions for
details about these attributes.
Send Entry Page and Entry Page Query Parameter information to the server by issuing a PUT
request to ccstore/v1/audienceContext/currentSession/entryPage/current. For
example:

PUT
ccstore/v1/audienceContext/currentSession/entryPage/current

{
"URL": "?a=a1&c=c1&d=d1&a=a2&e=",
"Referer": "[Link]
}

Both the landing page URL (URL) and referring site (Referer) fields are optional. The request
needs to send only the data to determine membership based on Entry Page and Entry Page
Query Parameter audience rules. Note that query parameters are conveyed in the URL field.
If audience rules depend only on the parameters and not the actual landing page URL, the
value for the URL field can omit the URL as long as it contains the parameters starting with
a ? character.

This request must include the X-CCVisitId header, which specifies the visit ID that is unique
to a user session. The storefront server uses the value of this header as the key to the cache
where this data is being stored. The same visit ID must be sent in the /audienceMembership
call, even if the shopper is not currently logged in.

Device rules
Device attributes specify the type of device (such as a computer, tablet, or phone) and
operating system (such as iOS or Android) the shopper is using to access the site. See
Understand audience definitions for details about Device attributes.
Send device information to the server by issuing a PUT request to ccstore/v1/
audienceContext/currentSession/deviceType/current. For example:

PUT
ccstore/v1/audienceContext/currentSession/deviceType/current

{
"deviceType": "Mobile",
"deviceOS": "iOS"
}

13-19
 Chapter 13
Add personalization to headless applications

This request must include the X-CCVisitId header, which specifies the visit ID that is
unique to a user session. The storefront server uses the value of this header as the
key to the cache where this data is being stored. The same visit ID must be sent in
the /audienceMembership call, even if the shopper is not currently logged in.

Send information in a single request

You can send geolocation, entry page, query parameter, and device information in a
single request by issuing a PUT request to ccstore/v1/audienceContext/
currentSession. For example:

PUT
ccstore/v1/audienceContext/currentSession

{
"geolocation": {
"country_code": "US",
"region_code": "CA",
"city": "SANDIEGO",
"timezone": "(GMT+11:00)",
"latitude": -25.4
},
"deviceData": {
"deviceType": "Mobile",
"deviceOS": "iOS"
},
"entryPage": {
"URL": "?a=a1&c=c1&d=d1&a=a2&e=",
"Referer": "[Link]
}
}

Sending a PUT request to the base ccstore/v1/audienceContext/currentSession

endpoint will replace all the data for each of the child endpoints, so use this endpoint
only if you want to send all the data at once.

Browsing rules
Browsing attributes let you track shopper browsing behavior, that is, views of products
or collections, in the current visit. See Understand audience definitions for details
about Browsing attributes.
The ccstore/v1/audienceContext/addBrowsingEvent endpoint caches behavioral
events. The custom application must call this endpoint with a X-CCVisitId header and
pass in the ID of the viewed item, the catalog ID, and whether the viewed item was a
product or collection.

13-20
14
Configure Tax Processing
Commerce integrates with both Avalara AvaTax and Vertex O Series to automatically
calculate sales tax in the shopping cart. Commerce uses the Avalara integration by default,
but you can easily switch to the Vertex integration.
If you process taxes with a different tax processor, you can use webhooks to integrate with
your tax processor so it calculates taxes in the shopping cart. You can also disable all tax
processor integration if you use an OMS or other external service to handle tax processing.
Some shoppers may have tax exempt status for certain purchases. For example, individuals
working for a charitable organization may be exempt from sales tax on items used in running
the charity. To learn how to configure Commerce and your tax processor to handle tax
exemptions, see Integrate with an external tax processor.
If you run multiple sites within a single instance of Commerce, these sites share the same tax
processor settings, but each site can have its own ship-from address. See Run Multiple
Stores from One Commerce Instance for more information about creating sites.
If you are using a loyalty program, you can configure tax processing to convert to and from
loyalty points currency. For information on loyalty programs, refer to Work with Loyalty
Programs.

Understand tax processor integrations

Commerce does not configure taxes, but integrates with tax processors that calculate sales
tax in the shopping cart.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You must have an active account for the tax processor you choose to integrate with
Commerce, including for the built-in Avalara and Vertex integrations.
Commerce automatically uses the tax processor you have enabled to calculate taxes for
every order placed on your store. The tax processor calculates sales tax as part of the pricing
operation. When the shopping cart is priced with a request to include tax pricing (when the
shopper begins the checkout process and when the order is submitted), Commerce sends
the order information to the tax processor, which calculates the total tax amount and sends it
back to Commerce. The response breaks down the tax into individual components, for
example, the total tax amount might include sales tax assessed by both the state and county.
Widgets on the checkout page automatically display the tax information.
Commerce is not involved in the settlement process and is not the system of record for any
aspect of orders, including taxes. Commerce issues Sales Order calls (instead of Invoice
calls) to tax providers to get the tax in a response.
Commerce uses a fallback method for calculating taxes when it cannot connect to your tax
processor’s web service in the event of an outage. See Monitor tax processors for details
about fallback tax calculation and information about configuring its settings.

14-1
 Chapter 14
Understand the Tax Code property

If you want to display SKU prices with tax included, for example prices that include
VAT, create a price group for those tax-inclusive prices. See Configure Price Groups
for more information. If your store uses price groups with tax-inclusive prices, you may
need to update your account on your tax processor’s site. For example, if your store
uses tax-inclusive prices, you must activate Avalara AvaTax with Global for your
AvaTax account.

Understand the Tax Code property

Each product and shipping method you create in Commerce has a Tax Code property.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Tax processors that integrate with Commerce use the value of the Tax Code property
when they calculate tax for each product or shipping method. The value you enter for
the Tax Code depends on your tax processor.
• For Avalara AvaTax, it is the Avalara tax code, also called goods and services
type. For example, if your store sells gift cards, the value of the gift card product’s
Tax Code property can be the Avalara tax code for Gift Certificates or
Electronically Delivered Gift Cards. For more information about tax codes in
AvaTax, go to the Avalara Help Center at [Link] and search for
tax codes.
• For Vertex O Series, it is the code you assigned to a taxability category in Vertex O
Series. For example, if your store sells gift cards, the value of the gift card
product’s Tax Code property is the code you assigned to the Gift Certificates/
Cards tax category in Vertex O Series.
Tax Code is not a required property; Commerce allows you to leave Tax Code blank
when you create a product or shipping method. However, it is best practice to assign a
Tax Code to every product and shipping method you create. Otherwise, the tax
calculations may return unexpected results, such as a higher-than-anticipated tax
amount. For example, if you leave a product or shipping method’s Tax Code property
blank, Vertex calculates the tax at the maximum rate that guarantees compliance.

Configure the AvaTax integration

The Avalara AvaTax integration is the default tax processor integration.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Commerce uses the tax processing settings you add when you configure the
integration when it communicates with Avalara during tax calculations. See
Understand tax processor integrations for overview information about all tax processor
integrations.
You must have an active AvaTax account to use this integration. To learn how to sign
up for an account and configure it, go to [Link]
Important: As a merchant, it is your responsibility to add the appropriate nexus
jurisdictions to your AvaTax company tax profile. (You configure your company profile
in your Avalara AvaTax Admin console.) Nexus jurisdictions tell AvaTax where and
when to calculate and report tax. All sales that occur in jurisdictions you have not
configured in AvaTax result in a tax calculation that returns a value of zero tax.

14-2
 Chapter 14
Configure the Vertex O Series integration

Commerce is not responsible for configuring or validating nexus jurisdictions. Visit the
Avalara Help Center at [Link] to learn about nexus jurisdictions.
Before you begin, make sure you have the following information for your AvaTax account:
• The company code.
• The account number.
• The license key.
To configure the Avalara tax processing settings, follow these steps:
1. Click the Settings icon, then select Tax Processing.
2. Select Avalara from the Tax Processor list.
By default, the Enable Tax Processor checkbox is selected for Avalara.
3. (Optional) Select Show Tax Summary to display an order’s tax amount in the cart,
checkout, and order summary pages, or deselect it to hide the tax summary. This
checkbox is selected by default.
If your store’s prices include tax, such as VAT, you likely do not want to display the tax
summary. However, if prices to not include tax, you should always display a tax summary.
This setting has no effect on the display of the tax summary in the emails your store
sends to customers. To learn how to remove the tax summary line from the order
summaries in emails, see Customize tax display in templates.
4. Enter your Avalara Account Information.
5. Click Save.
The following table describes the Avalara Account Information properties.

Property Description
Merchant ID The company code for your Avalara AvaTax
account.
Username The account number for your Avalara AvaTax
account.
Password The license key for your Avalara AvaTax account.
URL The web service URL for Avalara AvaTax.

Configure the Vertex O Series integration

The Avalara AvaTax integration is the default tax processor integration, but you can easily
switch to the Vertex O Series integration.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Commerce uses the tax processing settings you add when you configure the integration
when it communicates with Vertex during tax calculations. See Understand tax processor
integrations for overview information about all tax processor integrations.
You must have an active Vertex O Series account to use this integration. To learn how to sign
up for an account and configure it, go to [Link]
Important: As a merchant, it is your responsibility to add the appropriate tax jurisdictions to
your Vertex O Series taxpayer profile. (You set up your taxpayer profile in the My Enterprise
section of Vertex Central.) Jurisdictions you add to your taxpayer profile tell Vertex O Series

14-3
 Chapter 14
Integrate with an external tax processor

where and when to calculate and report tax. All sales that occur in jurisdictions you
have not configured in Vertex O Series result in a tax calculation that returns a value of
zero tax. Commerce is not responsible for configuring or validating jurisdictions. You
can find information about nexus and tax jurisdictions in the Vertex documentation,
which is available when you log into Vertex Central.
Before you begin, make sure you have the following information for your Vertex O
Series account on hand:
• The taxpayer code.
• The trusted ID.
• The username and password.
To configure the Vertex tax processing settings, follow these steps:
1. Click the Settings icon, then select Tax Processing.
2. Select Vertex from the Tax Processor list and select the Enable Tax Processor
checkbox.
3. (Optional) Select Show Tax Summary to display an order’s tax amount in the cart,
checkout, and order summary pages, or deselect it to hide the tax summary. This
checkbox is selected by default.
If your store’s prices include tax, such as VAT, you likely do not want to display the
tax summary. However, if prices to not include tax, you should always display a tax
summary.
This setting has no effect on the display of the tax summary in the emails your
store sends to customers. To learn how to remove the tax summary line from the
order summaries in emails, see Customize tax display in templates.
4. Enter your Vertex Account Information.
5. Click Save.
The following table describes the Vertex Account Information properties.

Property Description
Trust ID Your Vertex Trusted ID.
Merchant ID Your unique merchant ID.
Username The username for your Vertex O Series
account.
Password The password for your Vertex O Series
account.
URL The dedicated host-instance URL you received
from Vertex.

Integrate with an external tax processor

If you have an account with a tax processor other than Avalara AvaTax or Vertex O
Series, you can configure an integration that tells Commerce to use your tax processor
to perform tax calculations.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

To learn how to integrate with another tax processor, see Configure Tax Processors.

14-4
 Chapter 14
Configure Ship from Warehouse Locations

Configure Ship from Warehouse Locations

The Ship from Warehouse Location properties specify an address from which items sold on
your store are shipped.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The tax processor uses this information when calculating taxes.

• In the Avalara AvaTax, this address is referred to as a warehouse location.
• In Vertex O Series, this address is referred to as the physical origin.
If you run multiple sites within a single instance of Commerce, each site can have its own
ship-from address. For example, suppose you run two sites, one that sells items in the United
States, and another that sells items in France. For the US store, items would ship from your
warehouse in Chicago; for the French store, items would ship from your warehouse in Paris.
Although tax processor settings take effect immediately, changes to the ship-from address
must be published. This is because they are associated with a site, not with a tax processor.
To configure the Ship from Warehouse Location settings, follow these steps:
1. Click the Settings icon then select Tax Processing.
2. If you run multiple sites from a single Commerce instance, select the site whose address
you want to configure.
3. Enter your Ship from Warehouse Location Information.
4. Click Save.
5. Publish your changes.
The following table describes the Ship from Warehouse Location properties. Commerce does
not validate any of the address details; for example, it does not check to make sure the
Postal/ZIP Code you entered is valid for the Province/State.

Property Description
Country The country where the ship-from warehouse is
located.
Address Line 1 First line of the address where the ship-from
warehouse is located. For example, 1000 Smith
Street.
Address Line 2 Second line of the address where the ship-from
warehouse is located. For example, 4th Floor.
Address Line 3 Third line of the address where the ship-from
warehouse is located. For example, Suite 403.
City Name of the city where the ship-from warehouse
is located. This property is required if no
Postal/ZIP Code is specified.
Province/State Province or State where the ship-from warehouse
is located. This property is required if no
Postal/ZIP Code is specified.
Postal/ZIP Code Postal/ZIP code for the ship-from warehouse
location.

14-5
 Chapter 14
Disable all tax processors

Disable all tax processors

If your tax calculations are handled externally, such as in your order management
system, you can disable all tax processor integrations that calculate tax in the
shopping cart.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

To disable all tax processor integrations, follow these steps:

1. Click the Settings icon, then select Tax Processing.
2. In the Tax Processors list, select None.
3. Click Save.

14-6
15
Add personalization to headless applications
You can configure headless applications, such as native OS apps or custom web apps, to
establish a visit context for each shopper by evaluating the shopper's audience membership.

This section applies to Storefront Classic only.

Audiences allow you to target content to certain groups of shoppers. You define an audience
by creating a set of rules based on attributes of the shopper profile. See Define Audiencesfor
information about audiences. Custom (that is, headless) applications call /ccstore/v1/
audienceContext endpoints to use existing audiences to personalize content.

Before you begin adding personalization to a headless application, make sure that the
following tasks are already complete:
• Use the Commerce administration interface to create audiences and set locales and site
settings.
• Use the /ccadmin/v1/profiles endpoint to create shopper profiles.
• Make sure the custom application can call the Commerce REST APIs.
• Make sure the custom application conforms to the Internet Engineering Task Force
(IETF) cookie spec RFC 6265. The application must be able to store cookies specified in
REST responses and send them back in its REST requests.

View audience membership

You can use the REST API to pass a set of candidate audience IDs as query string
parameters, and get a response that includes the subset of IDs (if any) that pertain to
audiences a shopper belongs to. The must contain one or more of the following to identify the
shopper:
• Access token returned by the /login endpoint if the shopper is logged in or the soft-login
cookie returned from the /login endpoint if the shopper logged in previously.
If the request does not include either of these, the shopper is considered anonymous.
• Visit and visitor ID headers.
• x-ccsite header that identifies the site.
For example:

GET
/ccstore/v1/audienceMembership?filter=audience123,audience234,audience345
Authorization: Bearer <access_token>

x-ccsite: siteUS
X-CCVisitId: <visit ID>
X-CCVisitorId: <visitor ID>
Cookie: SOFT_LOGIN=plM0UbcY.... <encrypted profile ID>

15-1
 Chapter 15

The following is an example of the response returned:

200 OK
{
"audienceMembership": ["audience234", "audience345"]
}

Shopper Profile rules

The Shopper Profile category includes attributes of individual registered shoppers who
have logged in to a personal account. See Understand audience definitions for details
about the available Shopper Profile attributes.
In order to personalize based on these profile attributes, the shopper must have a
profile. Once a shopper has a registered profile, the custom application can log in the
shopper by using the ccstore/v1/login endpoint. This endpoint sets a persistent
cookie called SOFT_LOGIN that expires after 14 months. In order to personalize based
in profile attributes, the call to /audienceMembership must contain either the access
token or the SOFT_LOGIN cookie. Without either of these, the shopper is considered to
be anonymous.

Geolocation rules
The Geolocation category includes attributes that identify the current geographical
location of the shopper. See Understand audience definitions for details about the
available Geolocation attributes.
If the custom application sends its requests through a content delivery network, like
the storefront application does, then those requests, including the one to /
audienceMembeship, will include an additional header. For example:

X-Akamai-Edgescape:

georegion=263,country_code=US,region_code=MA,city=CAMBRIDGE,dma=506,pms
a=1120,areacode=617,county=MIDDLESEX,fips=25017,lat=42.3933,long=-71.13
33,timezone=EST,zip=02138-02142+02238-02239,continent=NA
,throughput=vhigh,asnum=21399

This header is all the /audienceMembership endpoint needs in order to determine

membership for Audiences with Geolocation rules. Otherwise, you must use the Store
API to communicate geolocation data to the storefront server. Issue a PUT request to
ccstore/v1/audienceContext/currentSession/geolocation/current. For example:

PUT
ccstore/v1/audienceContext/currentSession/geolocation/current
Authorization: Bearer <access_token>

X-CCVisitId: <visit ID>

{
"country_code": "US",
"region_code": "CA",
"city": "SANDIEGO",
"timezone": "(GMT+11:00)",

15-2
 Chapter 15

"latitude": -25.4
}

This request must include the X-CCVisitId header, which specifies the visit ID that is unique
to a user session. The storefront server uses the value of this header as the key to the cache
where this data is being stored. The same visit ID must be sent in the /audienceMembership
call, even if the shopper is not currently logged in.
All the fields in the request are optional. The custom application sends only the fields used in
the audience rules required for personalization. There is one exception: If a city is used in a
place rule, country_code must be sent along with city to disambiguate the city. To find the
place fields for any city, region, or country, query the /ccadmin/v1/places endpoint.

Entry Page and Entry Page Query Parameter Rules

Entry Page and Entry Page Query Parameter attributes specify how the shopper arrived at
the storefront. These rules can be based on landing page URL, referring site, or a variety of
default UTM and custom query string parameters. See Understand audience definitions for
details about these attributes.
Send Entry Page and Entry Page Query Parameter information to the server by issuing a PUT
request to ccstore/v1/audienceContext/currentSession/entryPage/current. For
example:

PUT
ccstore/v1/audienceContext/currentSession/entryPage/current

{
"URL": "?a=a1&c=c1&d=d1&a=a2&e=",
"Referer": "[Link]
}

Both the landing page URL (URL) and referring site (Referer) fields are optional. The request
needs to send only the data to determine membership based on Entry Page and Entry Page
Query Parameter audience rules. Note that query parameters are conveyed in the URL field.
If audience rules depend only on the parameters and not the actual landing page URL, the
value for the URL field can omit the URL as long as it contains the parameters starting with
a ? character.

This request must include the X-CCVisitId header, which specifies the visit ID that is unique
to a user session. The storefront server uses the value of this header as the key to the cache
where this data is being stored. The same visit ID must be sent in the /audienceMembership
call, even if the shopper is not currently logged in.

Device rules
Device attributes specify the type of device (such as a computer, tablet, or phone) and
operating system (such as iOS or Android) the shopper is using to access the site. See
Understand audience definitions for details about Device attributes.
Send device information to the server by issuing a PUT request to ccstore/v1/
audienceContext/currentSession/deviceType/current. For example:

PUT
ccstore/v1/audienceContext/currentSession/deviceType/current

15-3
 Chapter 15

{
"deviceType": "Mobile",
"deviceOS": "iOS"
}

This request must include the X-CCVisitId header, which specifies the visit ID that is
unique to a user session. The storefront server uses the value of this header as the
key to the cache where this data is being stored. The same visit ID must be sent in
the /audienceMembership call, even if the shopper is not currently logged in.

Send information in a single request

You can send geolocation, entry page, query parameter, and device information in a
single request by issuing a PUT request to ccstore/v1/audienceContext/
currentSession. For example:

PUT
ccstore/v1/audienceContext/currentSession

{
"geolocation": {
"country_code": "US",
"region_code": "CA",
"city": "SANDIEGO",
"timezone": "(GMT+11:00)",
"latitude": -25.4
},
"deviceData": {
"deviceType": "Mobile",
"deviceOS": "iOS"
},
"entryPage": {
"URL": "?a=a1&c=c1&d=d1&a=a2&e=",
"Referer": "[Link]
}
}

Sending a PUT request to the base ccstore/v1/audienceContext/currentSession

endpoint will replace all the data for each of the child endpoints, so use this endpoint
only if you want to send all the data at once.

Browsing rules
Browsing attributes let you track shopper browsing behavior, that is, views of products
or collections, in the current visit. See Understand audience definitions for details
about Browsing attributes.
The ccstore/v1/audienceContext/addBrowsingEvent endpoint caches behavioral
events. The custom application must call this endpoint with a X-CCVisitId header and
pass in the ID of the viewed item, the catalog ID, and whether the viewed item was a
product or collection.

15-4
16
Configure Payment Processing
Commerce includes several built-in integrations with payment gateways that let your store
accept various payment methods, including credit cards and PayPal payments.
In addition to the built-in integrations described in this section, you can use tools that
Commerce provides to create custom integrations with other payment gateways. See Create
a Credit Card Payment Gateway Integration for information about creating custom
integrations for a number of payment gateways.
If you run multiple sites within a single instance of Commerce, each site can use different
payment methods. The payment methods you configure are available to every site, but you
can assign a different subset of them to each site. Each new site you create automatically
inherits its payment methods from the default site, though you can change them on the
Payment Processing page. See Configure Sites to learn how to create multiple sites.

Configure payment settings

Before your store can accept payments, you must specify types of payments you accept and
countries from which you accept payments. You must also configure a payment gateway.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You must configure the following information in order for your store to accept payments:
• Billing countries: Countries from which your store accepts payments. The country in a
shopper’s billing address must be one of the billing countries you specify. Otherwise, the
order cannot be placed.
• Payment types: The types of credit cards your store accepts. These selections should
correspond with the payment selections you made in CyberSource or Chase Paymentech
when you configured your merchant account.
• Account information for your payment gateway.
To configure payment settings, follow these steps:
1. Click the Settings icon, then select Payment Processing.
2. If you run multiple sites from a single Commerce instance, select the site whose payment
methods you want to configure.
3. Select the payment types your store accepts.
4. Select one or more billing countries your store accepts and then click Save.
5. (Optional) Select a default billing country.
When a shopper checks out on your store, the default billing country is automatically
selected and appears at the top of the list of available billing countries.
The default billing country you select must be one of the billing countries you selected in
step 3. Otherwise, the storefront will not display the default country you selected.
6. Click the Payment Gateways tab and configure one or more gateways.

16-1
 Chapter 16
Configure the CyberSource integration

Configure the CyberSource integration

The CyberSource integration lets your store accept credit card payments.

This section applies to Storefront Classic only.

To use the integration, you must have both a CyberSource merchant account and an
activated CyberSource Secure Acceptance Checkout API profile. If you do not already
have a CyberSource account, go to [Link]/register to obtain an
evaluation account. An evaluation account lets you configure and test the
CyberSource integration. You will need to register for a paid merchant account
(including both Payment Gateway and Tokenization) before your store can go live and
accept payments from shoppers.
CyberSource Secure Acceptance Checkout API allows Commerce to send payment
card data directly from a shopper’s browser to CyberSource. No credit card data is
ever stored on Oracle servers. CyberSource securely stores all the card information,
replacing it with a unique identifier called a payment token. The payment token is
stored on CyberSource servers and in a property of the associated order on Oracle
servers. The token is used in all processing tasks associated with the order, including
settlement, refunds, and shipping.
To learn how to create a Secure Acceptance Checkout API profile, see Create a
Checkout API Profile in theSecure Acceptance Checkout API Integration Guide. This
guide is available on the CyberSource website.
Note: Commerce uses HMAC-SHA256 to generate the request signature and validate
the response signature for requests and responses sent as part of the CyberSource
integration. For more information, see Secure Your Service.

Configure Oracle Commerce settings

This section describes how to configure the CyberSource integration in Oracle
Commerce. Make sure you have your CyberSource account information on hand when
you perform the following steps.
1. Click the Settings icon, then select Payment Processing.
2. On the Payment Gateways tab, select CyberSource.
3. Under Account Information, click Use CyberSource and enter your
CyberSource account information.
4. Select one of the following environments and then enter your security keys for the
Secure Acceptance Checkout API. Each environment requires its own security
key. You cannot use the same security key for more than one environment.
Preview: Your store’s preview environment
Agent: The Commerce Agent Console
Storefront: Your production storefront
5. Click Save.
Account Information
These properties identify your CyberSource account. All properties are required.

16-2
 Chapter 16
Configure the CyberSource integration

Property Description
Merchant ID Merchant ID for your CyberSource account.
First Name First name and surname for the contact.
Last Name This is usually the name of the person listed as
the contact in your CyberSource account, but it
can be different.
Username Login name for your CyberSource account.

Security Keys for Secure Acceptance

These properties identify your CyberSource Secure Acceptance Checkout API profile. If you
configure properties for both the Storefront and Agent configurations, use the same
properties for both. All properties are required.

Property Description
Profile ID The ID for your CyberSource Secure Acceptance
Checkout API profile.
Access Key Authenticates your account with CyberSource.
Secret Key The secret key associated with the access key you
entered. The secret key signs the transaction data
and is required for each transaction.
SOP URL The URL used to send the form to CyberSource
for processing the payment.
For test and preview environments, set this to:
https://
[Link]/
silent/embedded/pay
For production environments, set this to:
https://
[Link]/
silent/embedded/pay

Test the CyberSource integration

Once the CyberSource integration is configured, you should be able to go to your store and
place a test transaction. If the transactions are successful, the orders will be visible in Oracle
Commerce reports in the CyberSource Business Center under Transaction Search.
Note: You cannot place test transactions in preview mode; you must place them from your
store. See Preview your store for information about preview mode.
The following page provides a list of test credit card numbers:

[Link]
test_cc_numbers/

16-3
 Chapter 16
Configure the PayPal integration

Note that to enable communication between CyberSource and your Commerce sites,
you must add the appropriate URL and HTTP methods to the allowedOriginMethods
property of each site object, and then publish your changes. For example, for a site
whose ID is siteUK:

PUT /ccadmin/v1/sites/siteUK HTTP/1.1

Authorization: Bearer <access_token>
x-ccasset-language: en

{
"properties": {
"allowedOriginMethods": {
"[Link] "GET,PUT,POST,OPTIONS"
}
}
}

For more information, see CORS support.

Configure the PayPal integration

The PayPal Express Checkout integration lets your customers pay for purchases with
their PayPal accounts.

This section applies to Storefront Classic only.

To use the integration, you must have either a Business or Premier PayPal account.
You should also have a PayPal Sandbox account with two test accounts.
You can configure the integration so that PayPal captures funds at the same time the
payment is authorized or you can capture funds later, for example, your order
management system can capture funds when the order ships.
For more information about PayPal Express Checkout, see Getting Started with
Express Checkout in the PayPal developer documentation.

Configure PayPal settings

To configure the PayPal settings, follow these steps:
1. Click the Settings icon, then select Payment Processing.
2. On the Payment Gateways tab, under Payment Gateways, select PayPal.
3. Under Account information, click Use PayPal.
4. Enter your PayPal merchant account information.
5. Click Save.
Account Information
These properties identify your PayPal account. All properties are required.

16-4
 Chapter 16
Configure the Chase Paymentech integration

Property Description
Client ID (Required) The API client ID for your PayPal
account.
Secret Key (Required) The API secret key for your PayPal
account.
Production If this setting is turned on, transactions occur on
the live PayPal production environment. If this
setting is turned off (default), transactions occur on
the PayPal Sandbox, a virtual testing environment.
Capture Payment Action Specify when PayPal should capture funds:
Order Placed: (default) PayPal authorizes payment
and captures funds when the order is submitted.
Order Shipped: PayPal authorizes payment when
the order is submitted but does not capture
payment. You are responsible for making sure
PayPal captures payment at a later time, ideally,
when the order ships. For more information, see
Capture Payments Later in the PayPal developer
documentation.

Understand PayPal requirements for account-based storefronts

Account-based storefronts have an additional requirement for shoppers who use PayPal as
their payment method. For more information, see Ensure PayPal shoppers provide first and
last name.

Configure the Chase Paymentech integration

The Chase Paymentech integration lets your store accept credit cards.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

To use the integration, you must have a Chase Paymentech merchant account.
The integration allows Commerce to send payment card details from a shopper’s browser to
an Oracle server, which then sends the card details to Chase Paymentech, where the
specified transaction (authorization, void, or refund) is performed. No credit card data is ever
stored on Oracle servers. The Chase Paymentech response contains an authorization code
and transaction reference number, which are stored in a property of the associated order on
Oracle servers.
The gateway does not support tokenization via the Orbital Customer Profile Management.
Therefore, a shopper who provided credit card details when submitting an order must provide
the details again for subsequent transactions, such as obtaining a refund.
Note: Commerce uses HMAC-SHA256 to generate the request signature and validate the
response signature for requests and responses sent as part of the payment gateway
integrations. For more information, see Secure Your Service.
The gateway does not support Address Verification Service (AVS), so to make sure cards are
not automatically declined you must do one of the following on your Orbital Virtual Terminal:
• Turn off mandatory AVS checking.

16-5
 Chapter 16
Configure the Chase Paymentech integration

• Configure your Merchant Selectable Response (MSR) settings to handle the AVS
response codes so that a card is not automatically declined for “information not
available” or “AVS not supported” codes. For more information about the response
codes, see AVS Response Codes on the Chase Paymentech Support Center.

Configure Chase Paymentech credit card settings

To configure the Chase Paymentech Credit Cards gateway settings, follow these
steps:
1. Click the Settings icon then select Payment Processing.
2. On the Payment Gateways tab, under Payment Gateways, select Chase
Paymentech Credit Cards.
3. Click Payment Gateway Enabled.
4. Select the environment to work in.
Preview: Your store’s preview environment
Agent: The Commerce Agent Console
Storefront: Your production storefront
5. Enter your Chase Paymentech account information.
6. Click Save.
Chase Paymentech Account Information
These properties identify your Chase Paymentech account. All properties are required.

Property Description
Username Login name for your Chase Paymentech
account.
Merchant ID Gateway merchant account number for your
Chase Paymentech account.
Merchant Secret Key The secret key associated with your Merchant
ID. The secret key signs the transaction data
and is required for each transaction.
Environment Specifies where transactions occur:
Sandbox: (default) Transactions occur on the
Chase Paymentech Sandbox, a virtual testing
environment.
Production: Transactions occur on the live
Chase Paymentech production environment.

16-6
17
Configure Shopper Settings
Shopper settings let you configure registration details, password policies, and session length
for registered customers. You do not have to publish changes you make to shopper settings;
they take effect as soon as you save them.
Note:The Commerce APIs provide endpoints that you can use to create custom properties
for shopper profiles that you can display on your store or use internally in the administration
interface. See Manage Shopper Profiles for more information.
In addition to these Shopper Settings, you can also restrict guest checkout. See Restrict
guest checkout for more information.

Configure the password policy

Password management is an important part of administering any site that includes personal
information.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This section describes the password management features included as part of Commerce
and includes the following topics:
• Configure strong passwords
• Force all passwords to expire
• Understand how forgotten passwords are handled

Configure strong passwords

Strong password checking lets you define criteria for new passwords; for example, you can
specify that new passwords cannot be duplicates of old ones or contain the same characters
as login names.
To configure strong passwords, follow these steps:
1. Click the Settings icon, then sShopper Settings.
2. Select one or more strong password settings.
• If you select Minimum Password Length, enter a number that specifies the
minimum number of characters.
• If you select Must Include a Symbol Character, enter, or add to, a list of symbols.
• If you select Cannot Be A Previous Password, enter a number that specifies how
many most recent passwords cannot be used.
• If you select Expire Password, enter a number that specifies the number of days
until a new password expires.
3. Click Save.

17-1
 Chapter 17
Configure the logged-in shopper session

Force all passwords to expire

In some cases, you may want to force the passwords of all registered users to expire
at the same time. Registered shoppers will have to reset their passwords the next time
they log in.
To force all passwords to expire, follow these steps:
1. Click the menu icon, then select Settings.
2. Select Shopper Settings from the Settings list.
3. Click the Expire All Passwords button.
4. Confirm that you want to force all passwords to expire immediately.

Understand how forgotten passwords are handled

Registered shoppers who cannot remember their passwords can use the Forgotten
Password feature in the storefront to set a new password. The process works as
follows:
1. The shopper clicks the Forgotten Password link in the login screen and enters
his or her email address.
The system validates that the email address matches an existing shopper profile.
If no match is found, the system does nothing, and the shopper does not receive
an email.
2. The shopper clicks the Send Request button. A one-time use link is sent by the
system to their email address.
3. Once the shopper receives the link and opens it, they are prompted to create and
confirm their new password.

Configure the logged-in shopper session

You can configure shopper sessions to automatically expire after a specified period of
inactivity.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The logged-out shopper can still access most areas of the store but must log in again
to access secure pages, such as their profile or the checkout page. This is sometimes
referred to as soft login.
To configure the logged-in shopper session, follow these steps:
1. Click the Settings icon, then select Shopper Settings.
When running multiple sites from your Oracle Commerce instance, your
configurations will be applied by site. Choose your site from the site picker at the
top of the Settings menu options.
2. Under Shopper Session, click Logged-In User Session Timeout.
3. Enter a number that specifies the session length, in minutes.
4. Click Save.

17-2
 Chapter 17
Configure guest checkout

Configure guest checkout

You can require that anonymous shoppers log into their accounts before they check out.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This feature can be used for anonymous shoppers who will log into either an individual
account or a business account.
To prevent guest checkout, follow these steps:
1. Click the Settings icon, then select Shopper Settings.
When running multiple sites from your Oracle Commerce instance, your configurations
will be applied by site. Choose a site from the site picker at the top of the Settings menu
options.
2. Under Guest Checkout, uncheck the Allow checkbox.
In addition to selecting this setting, your pages must be modified at a widget code-level to
restrict access to the Checkout UI itself. For details on doing so, see Manage Guest
Checkout.

Disable soft login

A logged-out shopper can still see personalized content based on their profile.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This is referred to as soft login. Soft login allows a registered shopper who is returning to the
site to be identified and their site experience to be personalized.
Soft login is a per site setting, and is enabled by default. You can use the /ccadmin/v1/
merchant/profilePolicies REST API endpoint to disable it. See Create a shopper profile
for details.
A shopper who is soft logged-in must log in to access their account page or to create an
order.

Configure account-based shoppers

You can allow a prospective account-based shopper to request registration of a new account
on your store.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Enabling this feature lets a shopper submit an account registration request for a new account
by providing required business details. The information is reviewed by an administrator from
the merchant side after the shopper submits the required details, and, if needed, the
administrator may request additional details such as credit checks. The registration request is
then either approved or rejected. If the request is approved, the new contact for the account
is activated.
To configure the account-based shoppers feature, follow these steps:

17-3
 Chapter 17
Configure shopper registration

1. Click the Settings icon, then select Shopper Settings.

When running multiple sites from your Oracle Commerce instance, your
configurations will be applied by site. Choose a site from the site picker at the top
of the Settings menu options.
2. Click from the Settings list.
3. Select Account-based Shoppers - Allow requests to register a new business
Account
4. Click Save.
The following provides additional details on what happens if this feature enabled:
• The Accounts page of the administrator user interface now includes a Registration
Requests tab. This area lets you view, search, and work with account registration
requests. For further details, refer to Configure Business Accounts.
• A Register for an account link appears on the Log In dialog box that is launched
from the Contact Login (for Managed Accounts) element of the Header widget.
Clicking the link displays a new business-to-business registration request form
dialog that the registrant fills in.
• The Store API for submitting a registration request can return a successful status.
The following provides additional details on what happens if this feature is disabled:
• The Register for an account link does not appear on the Log In dialog box that is
launched from the Contact Login (for Managed Accounts) element of the Header
widget.
• If a prospective shopper is in the process of filling out a Register form and submits
it, they see the “Account registration is not available” error.
• If there are registration requests with statuses of New, Review, More Info Needed,
or Rejected, the Registration Requests area remains in the Accounts area of the
UI.
• If there are no registration requests with statuses of New, Review, More Info
Needed, or Rejected, the Registration Requests area is hidden.
• The Store API to submit a registration request returns the error, “Account
registration is not available.”
Note: To enable the store user interface to allow account-based shoppers to submit an
account registration request, make sure you have a Contact Login element to the
Header widget in your site Home layout. For further details, refer to Create Page
Layouts that Support Different Types of Shoppers.

Configure shopper registration

You can configure shopper registration so that a shopper does not create a password
on the storefront, but instead completes registration by clicking a secure link in an
email your store sends to an email address the shopper provides.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This section describes how to enable and configure the secure registration flow for
shoppers. This feature is enabled by default for all new Commerce customers, starting
with Release 20.1.0. To support backward compatibility, the feature remains disabled if

17-4
 Chapter 17
Configure shopper registration

you upgraded to this release from Commerce 19.5.9 or earlier, though you can follow the
procedures in this chapter to enable and configure secure registration flow.

Understand secure shopper registration

Prior to Commerce 20A, a shopper who created a new account entered a name, email
address, and password as part of the registration request on the storefront. Now, when the
secure shopper registration flow is enabled, a shopper enters just a name and email address,
then submits the request. Commerce creates a shopper profile with an auto-generated
password and sends a New Account email with a secure, tokenized link. The shopper clicks
the link, then enters new password details to complete the registration.
When the secure registration flow is not enabled, a shopper who tries to create a new
account using an email address from an existing shopper profile sees a warning that the
email address is already associated with an account. When the secure registration flow is
enabled, Commerce does not display a warning, but sends a Forgotten Password email with
a secure, tokenized link. You can customize the Forgotten Password email template with text
that explains that the email address is already assigned to an account.
Similarly, if your store supports account-based commerce and a shopper tries to submit a
new account-registration request with an email address from an existing personal account,
Commerce no longer displays a warning that the address is already associated with a
shopper profile.

Enable the secure registration flow

To enable the secure registration flow, use the /ccadmin/v1/merchant/profilePolicies
endpoint in the Admin API to set the enableProfileRegistrationEmailCheck property to
true. For example:

PUT /ccadmin/v1/merchant/profilePolicies HTTP/1.1

Authorization: Bearer <access_token>

{
"enableProfileRegistrationEmailCheck": true

See Use the REST APIs for information you need to know before using the APIs.

Configure email templates

To implement the secure registration flow, you must enable the Forgotten Password and New
Account emails. If you are upgrading from release 19.5.9 or earlier, you must download the
latest versions of these email templates. The latest version of the New Account template
includes code to render the tokenized link and additional strings to support the new
registration flow. The latest version of the Forgotten Password template includes code that
displays a new customizable string if a shopper tried to register with an existing email
address.
Once you have downloaded the templates, customize them and then upload them. See
Customize Email Templates for more information.

17-5
 Chapter 17
Configure shopper registration

Update widgets
To implement the secure registration flow, make sure your layouts include the latest
version of the Login Checkout/Registration element. To replace a component with the
latest version, see Upgrade deployed widgets.

17-6
18
Configure Email Settings
Commerce lets you configure and automatically send different types of email notifications to
customers. In order to send email to customers, you must have an account with an email
service.
For information about customizing the templates for emails your store sends, see Customize
Email Templates.

Enable the types of email your store sends

You can use the Email Settings option in the administration interface to configure and
automatically send many types of emails from your store.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Commerce includes templates for the following types of email:

• Reset Password emails are sent when customers click the Forgotten Password link.
• Abandoned Order emails remind customers that they left unpurchased items in their
shopping carts. You can configure settings that determine when Abandoned Order
notifications are sent. See Configure Abandoned Cart settings for more information.
In addition, you can include product recommendations in Abandoned Order emails. For
information about product recommendations, see Display product recommendations. To
learn how to customize email templates to include recommendations, see Customize
Email Templates.
• Items Shipped emails let customers know that their orders have shipped. This notification
is sent when Commerce receives confirmation from your order fulfillment system that an
order has shipped.
• Order Placed emails let customers know that an order has been submitted for fulfillment.
This notification is usually sent as soon as an order is submitted, though if you specified a
remorse period, the email is sent as soon as the time you specified for the remorse
period has passed. See Understand the remorse period for more information about
remorse periods.
• New Account emails are sent when customers have registered on the storefront.
You can include product recommendations in New Account emails. For information about
product recommendations, see Display product recommendations.
• Back-in-stock email notifications are sent to shoppers after they have clicked the Notify
Me link when viewing a product that is out of stock, and they have provided their email
address. The Notify Me email template must be enabled, and configured, in order for the
back-in-stock email notifications to be sent when those products become available. See
Understand back in stock notifications for more information.
These email notifications are part of the built-in back in stock functionality. If your
Commerce environment integrates with an external system to track and notify shoppers
about inventory changes, enable the Inventory Update webhook, which notifies the
external system when SKUs are back in stock. See Understand webhooks for more
information.

18-1
 Chapter 18
Enable the types of email your store sends

• For details about Wish List emails, see Configure Wish Lists.
• For additional types of email you can send, see later in this topic.
You can customize each type of email your store sends. For example, you can edit the
text or change the colors and fonts to match those of your store, add a company name
and logo to email templates for account-based storefronts, or add site details if your
Commerce instance runs multiple sites. See Customize Email Templates for more
information.
In order to send email to customers, you must enable the email type, and specify the
name and email address that appears in the From field of that type of email. You can
specify a different name and email address for each type of email you enable.
To enable a type of email, follow these steps:
1. Click the Settings icon, then select Email Settings.
2. If you run multiple sites from a single Commerce instance, select the site whose
email types you want to configure and enable.
3. Select the email type you want to set up.
4. Click Enabled.
5. (Optional) In the From Name field, enter a display name for the sender.
6. In the From Email field, enter a valid email address to use as the sender.
Important: The address you enter must be a valid, active email account capable
of receiving messages. If you use Oracle to send transactional emails or other
outbound email for your Commerce site, which is typical, invalid sender email
addresses will result in an email block. If you use another email service, an invalid
email address will result in bounces; a high number of bounces may cause the
service to suspend your email account.
To test the address you want to use, send an email to it from any account and
verify it does not bounce.
7. Click Save.
If your environment includes the Commerce Agent Console, you can also send the
following types of email.
• Agent Cancel Order emails are sent when an agent cancels an order during the
remorse period.
• Agent Edit Order emails are sent when an agent amends an order during the
remorse period.
• Agent Forgot Password emails are sent when an agent resets a customer’s
password.
• Agent Return Order emails are sent when an agent processes a return.
• Agent Return Order Refund emails are sent when an agent processes a return
with a manual refund.
• Agent Shopper Registration emails are sent to customers who agents register on
your site.
If you are creating an account-based storefront, you can also send the following types
of email:
• Account Assignment Changed emails are sent when an active contact has been
added to an account. This could happen because a new active contact is added to

18-2
 Chapter 18
Enable the types of email your store sends

an account or an existing active contact has been moved from one account to another.
This email is also sent when an inactive contact that is already associated with an
account is activated or when a contact is removed from an account. The email contains a
link that the contact can click to set a new password for logging in to the storefront.
You can cut down on the number of emails contacts receive when you make multiple
account and role assignment changes at the same time. See Customize Email Templates
for more information.
• Role Assignment Changed emails are sent when one or more roles are added or
removed from a contact.
• Contact Deactivated emails are sent to contacts when they are removed from the system
and are no longer associated with any accounts.
• Account Deactivated emails are sent to all contacts associated with an account when that
account has been deactivated.
• Account Activated or New Contract Added emails are sent to all contacts associated with
an account when the account is activated, a contract is added, or if the account is moved
to a new parent, where it inherits the parent’s contracts by default.
Note: Emails are sent only when the account is active and has at least one contract.
• A number of emails notify contacts about events related to order approvals. For more
information about these types of emails, see Notify users of order approval-related
events.
If you are creating a storefront that lets account-based shoppers submit a new account
registration request for business accounts, you can also send the following specific types of
email that are specific to that process. For further details on the new account registration
request process, refer to Configure Business Accounts.
• New registration requests emails are sent to business users with the administrator or
account manager privilege.
• Account Request Approved - Manager emails are sent to administrators and account
managers.
• Account Request Rejected - Manager emails are sent to are sent to administrators and
account managers.
• Account Request Acknowledgment - User emails are sent to the account requester to let
them know that their account request has been received and is under review.
• Account Request Approved - User emails are sent to the account requester to let them
know that their account request has been approved.
• Account Request Rejected - User emails are sent to the account requester to let them
know that their account request has been rejected.
• Account Assignment Changed emails are sent to a user when they become a new active
contact. In this case, the account registration requester has been successfully added to
an account as an active contact. The email contains a link that the contact can click to set
a new password for logging in to the storefront. The email also instructs the user to
contact their organization if additional access information is needed.
If you are creating a storefront that lets an existing account-based shopper (contact) or a non-
account-based shopper submit a contact registration request , you can also send the
following types of email that are specific to that process. For further details on the contact
registration request process, refer to Configure Business Accounts.
Note: The templates for these emails can be found by going to the administration interface
and clicking on the administration menu. Next, click Settings > Email Settings. All templates

18-3
 Chapter 18
Enable the types of email your store sends

associated with contact request registration can be found in the Templates section of
the Email Settings page. All associated template names start with “Contact Request…”
• Email containing list of new contact registration requests - These are emails that
are sent to Administrators, Delegated Administrators, and Account Managers that
provide lists of new self-registration requests. Each email includes (at most) 25
contact self-registration requests and contains summary information about each
new request. Also, for each account that has requests, an email is also sent to all
Delegated Administrators on the account. The Administrators/Account Managers
emails have a link to the Accounts Administration Page to obtain more details, a
requested account ID, and a requested account name. The Delegated
Administrator emails do not have this additional information.
• Email to Delegated Administrators requesting they check on a contact registration
request – When an Administrator assigns a new account and saves the request,
updates the account on a request, and/or saves the request without accepting or
rejecting it, Commerce sends an email to the account’s Delegated Administrators
so that they will know to check for a request that needs attention.
• Emails to Administrators, Delegated Administrators, and Account Managers when
a contact request is accepted - When a contact self-registration request is
accepted (approved), one email is sent to all active internal users with the
Administrator and/or Account Manager privilege (if the approval was performed in
the Administrator user interface or via an Administrator endpoint). An email is also
sent to all Delegated Administrators on the account (regardless of where the
approval was performed).
• Emails to Administrators, Delegated Administrators, and Account Managers when
a contact request is rejected - When a contact self-registration request is rejected,
one email is sent to all active internal users with the Administrator and/or Account
Manager privilege (if the rejection was performed in the Administrator user
interface or via an Administrator endpoint). An email is also sent to all Delegated
Administrators on the account (regardless of where the rejection was performed).
• Email to a requester when Commerce receives a contact registration request -
When a new contact self-registration request is received, an email is sent to the
requester to communicate that the request has been received and is under review.
• Email to a requester when a contact registration request is approved - When a
new contact self-registration request is approved, an email is sent to the requester
to communicate that the request was approved. It also informs them that they will
receive a separate email with additional information, including login information, if
needed.
• Email to a requester when a contact registration request is rejected - When a new
contact self-registration request is rejected. It may also contain comments on why
the request was rejected
• Email to a requester when they have been activated as a contact - When the
contact is activated, an “Account Assignment Changed” email is sent to the
contact just as for any other newly activated contact who belongs to an account.
If your store allows shoppers to create and share purchase lists, you can enable
emails to be sent to purchase list recipients. To enable this feature, go to the Settings
section of the administration user interface. In the Email Settings area of Settings, add
a new template named “Purchase List Shared.”
The types of emails sent out with shared purchase lists include the following:

18-4
 Chapter 18
Configure Abandoned Cart settings

• An email that notifies a registered shopper that they are the recipient of a purchase list
being shared by another registered shopper. It tells them that they have been granted
access to purchase list XYZ (purchase list name). If the purchase list has a description
they will also see the purchase list description. There may also be list creator/owner
comments in the email.
It tells them that to access the purchase list, they need to view it on their profile on their
site.
Note: Site is the name (with a link to the correct URL) of the site from which the owner
shared the purchase list. The system does not take into consideration any restrictions on
the sites where the purchase list can be viewed.
• An email that notifies an account based contact that they are the recipient of a purchase
list being shared by another account based contact. It tells them that they have been
granted access to purchase list XYZ (purchase list name). If the purchase list has a
description they will also see the purchase list description. There may also be list creator/
owner comments in the email.
The system determines which site to include in the email as follows:
– If the site from which the owner shared the purchase list currently has a contract with
the account in whose context the list was shared (which will always be the case when
the list is shared from the provided widget), then that site will be included in the email.
Otherwise, the email includes any site that has a contract with the account in whose
context the list was shared.
– If the account in whose context the purchase list was shared has no sites with
contracts, an email is not sent and the purchase list is not shared. The system also
returns an error to the list creator.
– The system does not take into consideration any restrictions on the sites where the
purchase list can be viewed.

Configure Abandoned Cart settings

If you enable Abandoned Order emails, you can specify the number of days that must pass
before a shopping cart is considered abandoned and the minimum value that the cart must
contain before an Abandoned Order email is sent.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

To customize Abandoned Cart settings, follow these steps:

1. Click the Settings icon, then select Order Settings.
When running multiple sites from your Oracle Commerce instance, your configurations
will be applied by site. Choose a site from the site picker at the top of the Settings menu
options.
2. Under Abandoned Cart Settings, enter an integer for the number of days after which a
shopping cart is considered abandoned. The default setting is 7 days.
3. (Optional) Enter a value that specifies the minimum amount that the cart must be worth in
order for the system to send an Abandoned Cart email. The default setting is 0.
4. If you have configured the Cart Idle webhook, enter an integer for the number of minutes
after which a shopping cart is considered idle. The default setting is 20 minutes. See Use
Webhooks for more information about the Cart Idle webhook.
5. Click Save.

18-5
 Chapter 18
Ensure emails are not rejected as spam

Ensure emails are not rejected as spam

You must work with your email service provider to ensure your site can send and
receive emails correctly.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

In addition to completing general configuration, make sure the Sender Policy

Framework (SPF) record is configured appropriately for your domain to prevent emails
that your store sends from being rejected as spam.
To do so, add the following entry to the TXT record in your domain’s DNS zone file:

"include:_spf.[Link]"

Refer to [Link] for more information on the Sender Policy

Framework.

Configure an Alternate SMTP Email Relay

The REST APIs provided with Oracle Commerce allows you to use an alternate
Simple Mail Transfer Protocol (SMTP) relay to send email messages.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Oracle Commerce provides a default fully managed email service. However, if

necessary due to your own corporate policies or needs, you can use an alternative
SMTP email relay. When you use your own SMTP Relay, you assume full
responsibility for any deliverability concerns. Oracle Commerce’s responsibility in this
situation is limited to attempting to deliver the message to your SMTP relay,
Deliverability includes making sure your email is not treated as spam as discussed in
Ensure emails are not rejected as spam.
When you set up an SMTP email service property, your emailSMTPHost is added to the
proxy and SMTP traffic is routed through the proxy so that it can reach your SMTP
relay.
Commerce allows you to use the REST API to configure your email service types. For
example, if you issue a GET command to the /ccadmin/v1/email endpoint, and you will
see the default setting:

GET /ccadmin/v1/email

"emailServiceProperties":{
"emailServiceType" : "DEFAULT"
}

18-6
 Chapter 18
Configure an Alternate SMTP Email Relay

The response contains two JSON objects: the emailSerivceProperties that contains the
email service settings, and an emailNotificationTypes object, which contains information
on the available email types and their site-specific settings. For example:

{
"emailServiceProperties": {
"emailServiceType": "DEFAULT"
},
"links": [
{
"rel": "self",
"href": "/email"
}
],
"emailNotificationTypes": {
"ccadmin_user_password_reset_v1": {
"recommendationsSupported": false,
"displayName": "Oracle Commerce Administrator Password Reset",
"description": null,
"recommendationsStrategy": null,
"version": 1,
"enabled": false,
"fromEmail": null,
"recommendationsAllowAnyStrategy": true,
"recommendationsRestriction": null,
"fromName": null,
"recommendationsAllowRestrictions": true,
"includeRecommendations": false,
"id": "ccadmin_user_password_reset_v1",
"recommendationsPermittedStrategies": [],
"numberOfRecommendations": 12
},
"placed_order_v1": {
"recommendationsSupported": false,
"displayName": "Order Placed",
"description": null,
"recommendationsStrategy": null,
"version": 1,
"enabled": false,
"fromEmail": null,
"recommendationsAllowAnyStrategy": true,
"recommendationsRestriction": null,
"fromName": null,
"recommendationsAllowRestrictions": true,
"includeRecommendations": false,
"id": "placed_order_v1",
"recommendationsPermittedStrategies": [],
"numberOfRecommendations": 12
}
}
}

Important: Some of the configuration's details are not included in the response for security
reasons.

18-7
 Chapter 18
Configure an Alternate SMTP Email Relay

For information on working with email notifications, refer to Enable the types of email
your store sends.
Note that the endpoint configuration uses the site context specified using the X-CCSite
request header or the occsite query parameter. Omitting the site will display all of the
settings for your default site.
To set the SMTP email service type, issue a POST command to the /ccadmin/v1/email
endpoint and include the following properties:
• emailSMTPPort - Indicates the port to use when communicating with the SMTP
host. The port number should be either 465 or 587 and match the
emailSMTPAuthMethod. Note that you can specify an SMTP server in the
allowedURLs property by adding its domain name, such as [Link].
• emailSMTPHost - The SMTP host name.
• emailServiceType - This property is set to either DEFAULT or SMTP.
• emailSMTPAuthMethod - This identifies the authorization method as either SSL or
TLS. This property indicates if the authorization method used by your SMTP server
uses Secure Sockets Layer (SSL with port 465, legacy) or Transport Layer
Security (TLS with port 587, modern).
• emailSMTPUsername - The name used to log into the SMTP server.
• emailSMTPPassword - The user password for the SMTP Server. This field will not
be displayed when you issue a GET command.

For example:

"emailServiceProperties":{
"emailSMTPPort":"587",
"emailSMTPHost":"[Link]",
"emailServiceType":"SMTP",
"emailSMTPAuthMethod":"TLS",
"emailSMTPUsername":"smtpadmin"
"emailSMTPPassword":"smtpadminpassword"
}

If you issue a POST command to the /ccadmin/v1/email endpoint without passing in

"emailServiceType":"SMTP" an error occurs indicating that you cannot change
settings when the email service type is set to DEFAULT. If you do not provide all of the
required settings described earlier, you will also get an error.
Once you have issued a POST command to the endpoint with the required properties,
all email will switch to use the newly configured SMTP server.
Note that the endpoint configuration uses the site context specified using the X-CCSite
request header or the occsite query parameter. Omitting the site applies all of the
settings for your default site.
To switch back the email service type to use the default email service, issue a PUT
command to the /ccadmin/v1/email endpoint:

PUT /ccadmin/v1/email

"emailServiceProperties":{

18-8
 Chapter 18
Configure an Alternate SMTP Email Relay

"emailServiceType" : "DEFAULT"
}

Your SMTP configuration settings will be reset to their default, internal values.

18-9
19
Configure Internal User Accounts
Each person who works with the Commerce tools must have a valid user account to access
the system. One default Administrator account is included with your Commerce instance.
Only administrators can create and work with user accounts.
The Administrator account allows a designated person at your organization to log in and
create accounts for other users. The administrator must create an account for each internal
user who needs access to the system. The materials you receive from Oracle after you
subscribe to the Commerce service include instructions for creating accounts. If you need an
account or need changes made to an existing account, consult the administrator at your site.
Note: You do not have to publish new user accounts or changes you make to existing ones.
Changes to details like a user's name are available as soon as you save them. For
information on when to change a user's access control, refer to Edit user profiles.

Understand role-based access control

You can control your internal user's access to specific catalogs and price groups.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You have a great deal of flexibility in setting up access control to align with the way that your
business users work within your organization. You can configure access for situations where
your business runs multiple country or brand sites that use different catalogs and price
groups and are managed by separate teams. Or in situations where your business sells to
multiple accounts, you can configure access for the teams that manage their catalogs and
price groups.
You can enhance access control in these situations by creating security criteria that grant or
deny the ability to update specific catalogs or price groups. By adding security criteria to
roles, and then assigning the roles to your users, you can allow your users to make changes
only to the catalog assets and prices for which they are authorized.
By using multiple roles, privileges and security criteria, you can provide multiple levels of
access. For example, a graphic designer needs different access to the administration
interface than a merchandiser who sets up catalogs. Creating specific access controls
ensures that internal users have the correct access and abilities to perform their jobs
effectively.

Consider access control settings

When configuring access control, it's important to take the following into consideration:
1. Make sure that your access control strategy is easy to understand and easy to
implement. Overly complex access control strategies will be hard to maintain as your
environment grows.
2. Identify functions that the internal users perform, and what access is required. You can
set up restrictions to various data or areas to the administration interface depending on
the user's tasks.

19-1
 Chapter 19
Understand role-based access control

3. Identify roles that the internal users can be given. For example, is the user a
designer, a merchandiser or an administrator? These can all be roles that indicate
the user performs a specific task. A designer does not need access to all
administrative functions, but does need access to Design, Preview and Publishing
areas of the administrative interface.
4. Determine if there are security criteria necessary for controlling access. For
example, to limit the catalogs that a merchandiser has access to, you could create
a security criterion that identifies the specific catalog. This allows the merchandiser
to access only the specific catalog.
5. Create custom roles that contain security criteria created using the API, as well as
privileges. For information on working with the API, refer to Implement Access
Control for Internal Users.

Understand roles
Everyone who works with the administration interface or Agent Console must have a
valid user profile to access the system. There is a single default Administrator profile
included with your instance. Only administrators can create and work with user
profiles. Note that you do not need to publish user profiles when you create or update
them.
Each internal user is assigned a role, or multiple roles, which in turn, contains
privileges. Roles can also contain security criteria and access rights. Entities within a
role grant or deny access.
You must assign each user one or more roles. A role can contain privileges, security
criteria and/or generic access right entities. You cannot assign one of these entities
directly to a user, instead you assign a role that contains these entities. Commerce
includes a set of predefined roles, each containing a single privilege. You cannot add
privileges to, remove privileges from, or delete a predefined role.
Roles can determine whether to display a particular layout or content slot variant to a
user. This functionality is primarily used in the Agent Console. For additional
information, refer to Work with role-based layouts. Roles can also be used to grant
read or write access to a property.
The User Management area of the administration interface, which is available only to
users that have the Administrator privilege, allows you to assign roles to users. Note
that you cannot create or edit the contents of a role using the administration interface.
To do this, you must use the Admin API, which is described in Implement Access
Control for Internal Users.

Understand privileges
Privileges grant access to areas of the administration interface or Agent Console. For
example, the Catalog privilege provides access to the Catalog area of the
administration interface. A user needs at least one privilege to gain access to the
administration interface. Note that privileges cannot be edited or deleted. All privileges
are predefine; you cannot create a privilege.
Users can have multiple privileges across different roles. The user has all of the
privileges conferred by all of their assigned roles. For example, you could assign a
user a Dashboard privilege that allows access to the administration interface, as well
as the Agent privilege that enables access to the Agent Console. These privileges
could be assigned to a user by means of a single role, or two roles.

19-2
 Chapter 19
Understand role-based access control

The following table describes the access provided by the Commerce privileges. Note that
these privileges, and the roles that contain them, are separate from the roles that are
available for account-based storefront contacts.

Privilege Access
Administrator Full access to the administration interface.
CS Agent Full access to the Agent Console, with the exception of Manual
Adjustments. Note: This privilege is available only if the Agent
Console is available in your environment.
CS Agent Supervisor Full access to the Agent Console. Note: This privilege is available
only if the Agent Console is available in your environment.
Account Manager Full access to the Accounts page. Note: This feature may not be
enabled in your environment, refer to Configure Business
Accounts for information.
Catalog Full access to the Catalog page (you must also assign the Media
role if the user will upload images for products, SKUs, and
collections).
Dashboard Read access to the summary reports on the dashboard. The
dashboard is the landing page for the administration interface that
users see when they log into Commerce. All of the privileges that
control access to the administration interface allow the user to see
the dashboard. However only Dashboard or Administrator
privilege allows a user to see the summary reports. A user who
can see the summary reports on the dashboard requires the
Reporting or Administrator role to view the full reports.
Design Full access to the Design page.
Marketing Full access to the Marketing page.
Media Full access to the Media page.
Operations Full access to the Operations page.
Preview Access to the Preview button.
Publishing Full access to the Publishing page.
Reporting Full access to the Reporting page.
Search Full access to the Search page.
Settings Full access to all Settings pages except Access Control,
Extensions, Extension Settings, Email Settings and Web APIs
(access to those settings is granted by the Administrator
privilege).

Refer to Configure Business Accounts for additional information on roles for storefront
contacts.
Validate of privileges and roles
The following are validations that the system performs for all privileges and roles based upon
the action you perform:
• Create/Update Profile - The system validates that the profile has at least one role that
contains at least one privilege
• Update Profile - The system verifies that you are not removing the Administrator privilege
from yourself
• Delete Role - The system verifies that the user will still have the Administrator privilege
when the role is deleted. Note that predefined roles cannot be deleted.

19-3
 Chapter 19
Understand role-based access control

Understand security criteria

Security criteria restricts a user's ability to update specific catalogs or price groups. For
example, a user with the Catalog privilege might also have a security criterion that
narrows catalog access allowing the ability to update only CatalogA and no other
catalogs. A user's security criteria acts as a filter that narrows the specific data
accessible with their assigned privilege. Security criteria restricts update access but
does not restrict read-only access.
Using security criteria is optional. You can use them to prevent certain users from
updating specific catalogs or price groups. Note that to create, update or delete
security criteria, add them to roles or remove them from roles, you must use the API.
Refer to Implement Access Control for Internal Users for additional information on
working with the APIs.
A given security criterion applies either to catalogs or to price groups. There are three
types of security criteria that narrow user access:
• Grant: This grants update access to one or more specific catalogs or price groups.
For example a user who has a single Grant security criteria for Catalogs A and B
can update Catalogs A and B but cannot update any other catalogs.
• Deny: This denies access to one or more specific catalogs or price groups. For
example, a user who has a single Deny security criteria for Catalogs C and D can
update all catalogs except catalogs C and D.
• Grant None: This denies update access to all catalogs or price groups. A user with
a Grant None security criteria for catalogs cannot update any catalogs.

Price group security criteria applies not only to updating the properties of a price
group, but also updating all of the prices within the price group. For example, a
security criterion that grants update access to PriceGroup1 allows a user to update the
properties of PriceGroup1, as well as all the prices within PriceGroup1. Note that
update access to each price group is independent of access to any other price group,
even if you are using price group hierarchies. Anyone who has update access to the
Catalog privilege, and has update access to at least one price group, can create a
price group.
Catalog security criteria applies not only to updating the properties of the catalog, but
also updating all of the collections, products and SKUs within the catalog. For
example, a security criterion that grants update access to Catalog A also grants
access to the collections, products and SKUs within Catalog A. Any user that has the
Catalog privilege can create or update a product type. Similarly, any user who has the
Catalog privilege, and has update access to at least one catalog, can create a catalog.
When working with catalog hierarchy and shared items, the following rules apply:
1. If you have access to at least one parent of an item, then you have access to the
item. If a product is shared by two catalogs, and you have update access to one
parent of the product, then you can update the product.
2. To link an item to a parent, you need access to both the item and to its destination
parent.
3. To unlink an item from a parent, you need access to that parent.
4. To delete an item, you need access to all of its parents. If it has no parent, you
require access to the item itself.

19-4
 Chapter 19
Understand role-based access control

Note that in this case, parent indicates an immediate parent, which can be a catalog, a
collection or a product.
You can create, update or delete an unassigned product or collection if you have the Catalog
privilege and access to at least one catalog. You can also link unassigned collections to the
catalog.
A product or collection that belongs to both an unassigned collection and an assigned
collection of a catalog is subject to the rules stated earlier but without counting the
unassigned collection as a parent. For example, if product P belongs to both the unassigned
collection C1 and the assigned collection C2, the user must have access to C2 to update
product P, even though they have access to unassigned collections.
Access to a legacy secondary catalog and access to its primary catalog are independent of
one another. The primary and secondary catalogs are treated the same as any other
catalogs, with respect to access control.
Access to an independent catalog automatically gives a user access to all of the filtered
catalogs on which the independent catalog is based. It is also possible to give a user access
to a filtered catalog, but not to its base independent catalog. The following table shows the
access control rules regarding filtered catalogs and their base independent catalogs:

Capability Available to user with access Available to user with access

to base independent catalog? to filtered catalog but not
based independent catalog?
Control if a product in the base Yes No
independent catalog appears by
default in all filtered catalogs.
Determine to which catalogs a Yes No
product in the base independent
catalog is directly linked.
Determine if a product in the Yes Yes
base independent catalog
appears in the filtered catalog.
Determine if a product in the Yes No
base independent catalog
appears in a different filtered
catalog.
Update any other product Yes Yes
property for any product in the
base independent catalog. This
does not include the properties
listed earlier.
Update a property of the filtered Yes Yes
catalog.
Delete the filtered catalog. Yes Yes
Delete a product that is in the Yes, if the user has access to all No
base independent catalog. of the immediate parents of the
product.
Link or unlink a product in the Yes No
base independent catalog to or
from a parent collection.
Create a product in the base Yes No
independent catalog.

19-5
 Chapter 19
Understand role-based access control

Capability Available to user with access Available to user with access

to base independent catalog? to filtered catalog but not
based independent catalog?
Create any catalog, including Yes Yes
creating a filtered catalog in any
base independent catalog.
Create, update, link, unlink or Yes, although link and delete No
delete a collection in the base actions may require access to
independent catalog. other parent catalogs of the
collection.
Create, update or delete SKUs Yes No
under a product in the base
independent catalog.

When working with products and media, the user needs access to a product to
perform the following media-related operations:
• Add a media item to the product from the Media Library. To upload new media
items to the product, the user also needs the Media privilege
• Update the product-specific override values of the properties of a media item
assigned to the product. For example, Alt Text or Title
• Remove the product-specific override values of the properties of a media item
assigned to the product. For example, resetting the properties to their default
values
• Reorder the media items assigned to the product
• Specify which media item is the primary one for the product
• Remove a media item from the product
Access to a product's prices is controlled separately from access to the product itself.
A user with the Catalog privilege can update a product's prices without having access
to the product itself, as long as the user has access to the price group in which the
prices reside. Access to a product does not provide access to its prices. Only access
to a price group allows a user to update prices. The same applies to SKUs and their
prices. Note the following:
• To create a product, or update a product that was imported without prices, a user
must have access to every price group for which the includeAllProducts flag is
set.
• To delete a product, a user needs access to all price groups containing prices for
the product.
Security criteria apply when catalog assets and prices are imported, either using the
Import function in the UI, or when a logged-in user performs a bulk import. Bulk
imports performed by registered applications are not subject to security criteria. If you
use catalog security criteria, it is recommended that you use APIs rather than the UI
for any catalog imports. This allows you to receive information about any records that
fail to import due to access restrictions.
Combine security criteria
A user can have multiple security criteria within one role, or across different roles. The
following examples show the effects of having multiple security criteria:

19-6
 Chapter 19
Understand role-based access control

• A user with Grant access to PriceGroup1 and PriceGroup2 can update both PriceGroup1
and PriceGroup2
• A user with Grant access to Catalog 1 and Catalog2 can update Catalog2, Catalog2, and
catalog assets whose immediate parents belong to Catalog1 or Catalog2
• A user with Deny access to PriceGroup1 and PriceGroup2 cannot update PriceGroup1 or
PriceGroup2
• A user with Deny access to Catalog1 and Catalog2 cannot update Catalog1, Catalog2 or
any catalog assets whose immediate parents belong only to Catalog1 or Catalog2
For example, consider the following rules. Note that in each of the following rules, the assets
are either catalogs or price groups:
• Grant Asset1 + Deny Asset2 = Grant Asset1
• Grant Asset1 + Deny Asset1 = Grant None
• Grant Asset1 + Deny Asset1 + Grant Asset2 + Deny Asset3 = Grant Asset2 (Grant and
Deny Asset1 cancel themselves out.)
• Grant None + any other security criteria = Grant None
Understand system-generated roles
If a user with security criteria creates a catalog or price group, the system may generate a
role for that user to ensure that he or she has access to the asset just created. The system-
generated role contains a security criterion that grants access to the catalog or price group. If
the user subsequently creates another catalog or price group, the system adds a security
criterion to the role, granting access to the new asset.
System-generated roles are visible in the Advanced section of the user's details in the User
Management area of the administration console. System-generated roles function the same
as other roles, except that the system may keep adding security criteria.

Generic access rights

The access control described here does not modify existing functionality related to access
rights and the property-level access control that you use to meet the requirements of the
General Data Protection Regulation (GDPR). However, if you use APIs it is important to note
that privileges are a type of access right. Therefore non-privilege access rights are referred to
as generic access rights. If a role contains generic access rights, they are visible in the
Advanced section of the role's details in the User Management area of the administration
console. Refer to Refer to Implement Access Control for Internal Users for more information
on using generic access rights to control access to the properties of data items.

Understand when access control takes effect

Changes to the contents of a user's access takes effect as follows:
1. Changes to a user's security criteria take effect the next time the user logs in. The user's
access to specific catalogs or price groups does not change during their current session
2. Changes to a user's privileges take effect immediately, whenever any aspect of the UI or
functionality checks for privileges
3. Changes to a user's generic access rights take effect immediately, when the user tries to
access a property that is subject to access rights

19-7
 Chapter 19
View role contents

View role contents

All internal users must have at least one privilege, and therefore at least one role, to
gain access to the administration interface.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

When creating new or editing existing users, you must assign them roles. Roles can
contain privileges that grants the user access to various functions. To view the
available roles, use the User Management area of the administration console.
Note that roles and roles and security criteria cannot be created in the administration
console, to create roles and security criteria, you must use the Admin API. For
information on using the API, refer to Implement Access Control for Internal Users. In
the User Management area of the administration console, you can assign roles to
users and view the contents of roles.
To view a user's roles:
1. Select User Management from the administration console. This displays the User
Management screen.
2. You can select a user based upon specific roles by using the All Roles dropdown
and selecting or entering the roles. This will display all users that have this role. Or
you can select a user alphabetically, or by whether or not they are internally or
externally managed.
3. When the user's page has opened, in addition to their email and name information,
you will see all of the roles associated with the user listed under the Roles section.
You can add or remove roles by clicking Edit List.
4. Select the roles to add or remove.
5. Click Done to save the changes.
You can review or edit any system-generated roles using the Advanced section of the
User Management page. System-generated roles are roles that the system creates for
a user to ensure that they have access to any catalog or price group they may have
created. The system-generated role also contains a security criterion that grants
access to the catalog or price group the user created.
You can review the roles themselves by selecting the role listed next to a user's name
in the User Management screen. This displays the name of the role, a description and
the privileges and security criteria contained in the role. Use the Advanced button to
see the any generic access rights contained in the role. Roles and security criteria can
only be created using the API. Refer to Implement Access Control for Internal Users
for information on working with the API for access control.

Create new user profiles

One default Administrator profile is included with your Commerce instance, but you
can add as many internal user profiles (including administrators) as you need.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Only administrators can create and work with user accounts.

19-8
 Chapter 19
Edit user profiles

In order to comply with the Payment Card Industry Data Security Standard (PCI DSS),
Commerce secures all logins to the administration interface with multi-factor strong
authentication. This means that each user must enter their username and password, plus a
one-time passcode, each time they log into the administration interface. See Access the
Commerce administration interface to learn about setup tasks new users must perform before
they can log into the administration interface for the first time.
Administrators do not assign login passwords to user profiles. Once you create a new profile,
Commerce sends an email to the address you added to the profile. The email includes a link
that the user clicks to set their password. If the link has expired when the user clicks it,
Commerce displays a page where the user can request a new link.
The password must be at least eight characters long and contain at least one number, one
uppercase letter, and one lowercase letter. It cannot contain the email address and cannot
match any of the last four passwords.
In addition, the password is checked against a dictionary of weak passwords that Commerce
maintains. If a user attempts to set a password that matches one of the entries in this
dictionary, the password is rejected. The dictionary is the same one used for shopper
passwords, as described in the Create a shopper profile. Note, however, that additional
entries created using the updateRestrictedWords endpoint in the Admin API are applied only
to shopper passwords, and not to passwords for internal users.
To create a new user profile, follow these steps:
1. Click the User Management icon.
2. Click New User.
3. Enter the information that identifies the new user and select an appropriate role. See the
table that follows this procedure for information about each field.
4. Click Save.
The following table describes the properties that identify a Commerce user profile. All
properties are required.

Property Description
Email The user’s email address. This usually functions
as the username during login, and is the address
where the password link is sent.
Roles Assign one or more roles to the profile. See
Understand Role-based Access Control for more
information.
First Name The user’s first name.
Last Name The user’s last name.

Note that a user's page contains a read-only Externally Managed checkbox. This checkbox
is selected by default if the user's details are managed in an external system. If a user is
managed externally, the only change that can be made in User Management is the ability to
identify which roles are assigned to the user.

Edit user profiles

You can edit a profile’s first name, last name, email address, and assigned roles.

19-9
 Chapter 19
Edit user profiles

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You can also reset the password for the profile and the secret key that links the profile
to Oracle Mobile Authenticator.
To edit a user profile, follow these steps:
1. Click the User Management icon.
2. Click the name of the user whose profile you want to change.
3. Once you have made your changes, click Save.
To edit roles to the user profile, click Edit List under Roles. The list of assigned roles
appears in the Selections pane. Search for a name or ID of a role to see it displayed
in the search results. Double click on the role to add it to the selection. To delete a
selection, select the X next to its name. Note that you can only create roles using the
API. For information on using the API to create roles, refer to Implement Access
Control for Internal Users.
The user can change the password at any time by clicking the Forgot Password? link
on the administration interface login page and entering the email address associated
with their profile, as described in the previous section. You can also force them to reset
it.
To force a user to reset their password, follow these steps:
1. Click the User Management icon.
2. Click the name of the user.
3. Click Reset Password.
4. At the prompt, click Reset to confirm.
Commerce sends a link to the email address associated with the user’s profile that
the user can click to reset their password.
You can reset the secret key that links a user’s profile with Oracle Mobile Authenticator
(OMA). You will need to reset the key if the original link in the user’s email has expired.
When you reset a user’s secret key, they cannot log into the administration interface
again until they reconfigure OMA as described in Add your Commerce profile to Oracle
Mobile Authenticator.
To reset a user’s secret key, follow these steps:
1. Click the User Management icon.
2. Click the name of the user.
3. Click Reset Key.
4. At the prompt, click Reset to confirm.
Commerce sends a message to the email address associated with the profile. The
message includes several ways that the user can associate the new key with
OMA. See Access the Commerce administration interface for more information.
Understand access control changes
Whenever you change a user's security criteria, the change occurs the next time that
the user logs in. While the user is logged in, access to specific catalogs or price
groups does not change.

19-10
 Chapter 19
Deactivate and reactivate user profiles

When you change a user's privileges, the change occurs immediately, meaning any time
system checks for privileges, it will retrieve the new privileges.

Deactivate and reactivate user profiles

You cannot delete internal user profiles but you can deactivate them.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Deactivated profiles cannot be used to access the service. Keep the following in mind before
you deactivate user profiles:
• Only users with the Administrator role can deactivate and reactivate profiles.
• You cannot deactivate the last user with the Administrator privilege.
• You cannot deactivate the profile you are currently logged in with.
• You can reactivate any deactivated profile.
• Commerce does not notify users when their profiles are deactivated or reactivated.
• Deactivating a profile does not automatically expire its password or secret key.
To deactivate a user profile, follow these steps:
1. Click the User Management icon.
2. Click the name of the user whose profile you want to deactivate.
3. Click the Deactivate button.
4. Confirm that you want to deactivate the profile.
To reactivate a user profile, follow these steps:
1. Click the User Management icon.
2. Click the name of the user whose profile you want to reactivate.
3. Click the Reactivate button.
4. Confirm that you want to reactivate the profile.

Access the Commerce administration interface

All users who work in the administration interface must have an internal user profile and must
understand how to log into the administration interface.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This section describes the tasks required to prepare your profile and access the
administration interface:
• Understand multi-factor authentication
• Prepare to use multi-factor authentication
• Download Oracle Mobile Authenticator
• Add your Commerce profile to Oracle Mobile Authenticator
• Create your password

19-11
 Chapter 19
Access the Commerce administration interface

• Log into the Commerce administration interface

Understand multi-factor authentication

Multi-factor authentication is an authentication mechanism that requires a user to
present at least two of the following three types of credentials when logging into an
account:
• Something you know, like a password.
• Something you have, like a smart card or a one-time passcode.
• Something you are, like your fingerprint.
The Payment Card Industry Data Security Standard (PCI DSS) requires multi-factor
authentication for any user who accesses an administrative environment that handles
card data. Multi-factor authentication helps keep intruders out by providing an extra
layer of security when users require access to environments that contain sensitive
information.
Commerce implements this requirement by ensuring that each internal user enters
their username and password, plus a one-time passcode (generated by Oracle Mobile
Authenticator) every time they log into the administration interface.

Prepare to use multi-factor authentication

You will receive an automatically-generated email that contains the information you
need to perform the steps to set up multi-factor authentication.
• If you are a new Commerce user, you will receive an automatically-generated
email whose subject line is Set Up Your Oracle Commerce Login once a
Commerce administrator has created your profile.
• If you are an existing Commerce user, you will receive an automatically-generated
email with the subject line Your Oracle Commerce Secret Key Reset once your
site has been updated to a release of Commerce that requires multi-factor
authentication.
Your email contains the information you need to perform the following steps:
1. Download Oracle Mobile Authenticator to your iOS, Android, or Windows device.
2. Add your Commerce profile to Oracle Mobile Authenticator using the secret key in
the email.
3. Create your password for your Commerce profile.
4. Log into the Commerce administration interface with your username, password,
and a one-time passcode generated by Mobile Authenticator.
Keep the following information about the email in mind:
• You will receive a separate email for each of your environments and must follow
this procedure for each one. For example, if you have three environments, you will
need to follow the procedure three times – once for each environment – in order to
access the administration interface in each environment.
• If you did not receive the automated email, check your spam or junk mail folder.

Download Oracle Mobile Authenticator

Oracle Mobile Authenticator (OMA) is a free app that generates the one-time
passcodes (unique, random numbers) you enter each time you log into the Commerce

19-12
 Chapter 19
Access the Commerce administration interface

administration interface. OMA does not require cell service or an internet connection to
generate one-time passcodes.
OMA is available for Android, iOS, and Windows devices, including PCs running Windows
8.1+. The iOS app is available at the Apple app store, the Android app is available at the
Google Play store, and the Windows app is available at the Microsoft store, all under the
name Oracle Mobile Authenticator. Visit the appropriate app store for your device to learn
about system requirements and download the app.
Download OMA to your device, launch it, and accept the end user license agreement. Then
follow the instructions in Add your Commerce profile to Oracle Mobile Authenticator to link
your Commerce profile to OMA.

Add your Commerce profile to Oracle Mobile Authenticator

After you install the Oracle Mobile Authenticator (OMA), you need to link it to your Commerce
profile. You do this by adding your profile’s secret key to OMA. Make sure you have the email
you received when your profile was created; it contains everything you need to access the
Authenticator Details page, where you add your profile to OMA in one of the following ways:
Scan the QR code
Click the Create an OMA Entry link
Enter the key manually
Scan the QR code
If you are viewing the email on a device where OMA is not installed, like your computer, you
can open OMA on your mobile device and scan the QR code that you access from the email.
If you are unable to successfully scan the code, see Click the Create an OMA Entry link or
Enter the key manually for alternate ways to add your profile to OMA.
1. Open the OMA app on your mobile device, then tap Add Account.
2. Open the Set Up Your Oracle Commerce Login email and click the Oracle Mobile
Authenticator Setup link to open the Authenticator Details page.
3. Scan the QR code that appears on the page using your device’s camera.
Depending on your mobile device’s security settings, you may be prompted to enter your
user name and password.
After configuration is complete, the passcode generator screen begins displaying one-
time passcodes.
If you scan an expired QR code, Commerce displays an error page. Contact your Commerce
administrator, who can reset the secret key. Once the key is reset, you will receive another
email.
Now you can continue to the steps in the next section, Create your password.
Click the Create an OMA Entry link
If you are viewing the Commerce email on the same device where OMA is installed, you can
simply click an enrollment link that opens the OMA app on your device and starts the
configuration process.
1. Open the Set Up Your Oracle Commerce Login email on the device where OMA is
installed and tap the Oracle Mobile Authenticator Setup link to open the Authenticator
Details page.
2. Tap the Oracle Commerce link.

19-13
 Chapter 19
Access the Commerce administration interface

Depending on your mobile device’s security settings, you may be prompted to

enter your user name and password.
After configuration is complete, the passcode generator screen begins displaying
one-time passcodes.
If you click an expired link, Commerce displays an error page. Contact your
Commerce administrator, who can reset the secret key. Once the key is reset, you will
receive another email.
Now you can continue to the steps in the next section, Create your password.
Enter the key manually
You can manually type or cut and paste the secret key into OMA.
To see the secret key, open the Set Up Your Oracle Commerce Login email and click
the Oracle Mobile Authenticator Setup link to open the Authenticator Details page. The
secret key is displayed at the bottom of the page.
To enter the secret key into OMA:
1. Open the OMA app on your device, then tap Add Account.
Depending on your mobile device’s security settings, you may be prompted to
enter your user name and password.
2. Tap Enter key manually.
3. Under Select Account Type, tap Oracle.
4. In the Account field, enter Commerce.
5. In the Key field, enter the secret key.
6. Tap Save.
After configuration is complete, the passcode generator screen begins displaying
one-time passcodes.

Create your password

Administrators do not assign login passwords to new user profiles. To create a
password for your new profile, open the Set Up Your Oracle Commerce Login email
and click the Create Password link. (If the link has expired when you click it,
Commerce displays a page where you can request a new link. You will need to supply
a one-time passcode when you reset your password. See Log into the Commerce
administration interface for more information.)
Your password must be at least eight characters long and contain at least one number,
one uppercase letter, and one lowercase letter. It cannot contain your email address.
The password is also checked against a list of weak passwords that Commerce
maintains. If you try to create a password that matches one of the entries in this
dictionary, the password is rejected.
Now you can log into Commerce. See Log into the Commerce administration interface
for details.

Log into the Commerce administration interface

Once you have linked your Commerce profile to Oracle Mobile Authenticator (OMA)
and created your password, you are ready to log into the administration interface.

19-14
 Chapter 19
Access the Commerce administration interface

Important: You must generate a new one-time passcode each time you log into the
administration interface. This includes logging back in if you have been automatically logged
out. Commerce does not currently mark a device as safe or save passcodes across sessions.
To log into the administration interface, follow these steps:
1. Navigate to the Commerce sign in page with the URL provided to you by your
administrator.
2. Enter your username and password.
3. Launch the OMA app on the device where you installed it.
A one-time passcode appears and the countdown begins until a new passcode is
automatically generated.
4. On the Commerce sign in page, enter the code into the One-Time Passcode box and
click Log In.

19-15
20
Configure Shipping
A shipping method contains one or more shipping regions and shipping charges.
Your store must contain at least one shipping method that shoppers can select during
checkout. If you create and enable more than one shipping method, shoppers choose from a
list of the enabled shipping methods. Then, the selected method is associated with the
shipping group selected in the shoppers’ order.
If you run multiple sites within a single instance of Commerce, these sites can share shipping
methods, or you can create site-specific shipping methods. See Create a shipping method for
information about assigning shipping methods to specific sites. See Configure Sites to learn
how to create multiple sites.

Create shipping regions

Shipping regions specify geographic areas your store will ship to.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Grouping shipping destinations into regions makes it easier to create shipping methods. For
example, to create a ground shipping method for a store based in the United States, start by
creating a shipping region that includes the 48 contiguous U.S. states. When a customer
enters a shipping address either at checkout or when creating a profile, the logic in the
Customer Address widget allows the customer to pick from only countries and regions that
are used in enabled shipping methods.
To create a shipping region, follow these steps:
1. Click the Settings icon, then select Shipping Methods.
2. Click New Shipping Region.
3. Enter a name for the shipping region.
4. Select one or more countries to ship to and then one or more regions within each
selected country.
Tip: When you select a country, all its regions are automatically selected by default. To
select only some regions, either deselect the regions you do not want to include or
uncheck the Select All checkbox and then individually select regions.
5. Click Save.

Create a shipping method

You must create at least one shipping method, even if your shipping is handled by a third-
party fulfillment system.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

20-1
 Chapter 20
Create a shipping method

Oracle Commerce supports the following shipping methods:

• Internally priced shipping method - A shipping method created in the
administration interface whose price and availability is determined during checkout
using internal rules.
• Externally priced shipping method - A shipping method created in the
administration interface whose price and availability is determined using a
combination of internal rules and the shipping calculator service.
During checkout, Oracle Commerce determines which externally priced shipping
methods are available based on internal rules. The available shipping methods
and costs are sent to the shipping calculator service in the request. The shipping
calculator service responds with some or all of the available methods and their
prices and these available shipping methods are displayed to the shopper with the
returned price. Refer to Integrate with External Shipping Calculators and Use
Webhooks for complete information on using this method.
• External shipping method - A shipping method returned by the external shipping
calculator service that does not have an internal representation in the
administration interface. The price and availability are determined entirely by the
service. Refer to Integrate with External Shipping Calculatorsand Use Webhooks
for complete information on using this method.
To create a new shipping method using the administration interface, follow these
steps:
1. Click the Settings icon, then select Shipping Methods.
2. Click New Shipping Method.
3. Select the type of shipping method that you want from the drop-down list.
4. Enter the information that identifies the new shipping method. See the table that
follows this procedure to learn about the information to enter in each field.
5. Click Save.
The following table describes the properties that identify a shipping method.

Property Description
Display Name (Required) A name for the shipping method.
Description A short description of the shipping method.
This does not appear on your store.
Internal Name A string that is hidden from shoppers that lets
you create multiple shipping methods with the
same display name. The internal name makes
it easier to manage shipping methods when
working with shipping methods in the
administration interface, for example, when
viewing your list of shipping methods or
creating shipping promotions.
Tax Code A tax code to assign to the shipping method
that allows your tax processor to make the
appropriate tax calculations. For more
information, see Configure Tax Processing.
Enabled Select the checkbox to make the method
available on your store.
By default, shipping methods are enabled.

20-2
 Chapter 20
Specify a fallback shipping method

Property Description
Use as fallback shipping method If your store integrates with external
calculators for shipping services (such as
UPS, USPS, or FedEx), you can specify
internal shipping methods that will be offered
to shoppers when Commerce cannot connect
to external shipping service’s web service, for
example, in the event of an outage. See
Specify a fallback shipping method for more
information.
Eligible for Products with Shipping Surcharge Select the checkbox to make the method
available to ship products that have shipping
surcharges.
Sites If you run multiple sites within a single instance
of Commerce, you can make a shipping
method available to all sites or only to sites
you specify.
Select the Applies to All Sites checkbox if you
want this shipping method to be available on
all sites. If you want this shipping method to be
available only on specific sites, uncheck the
checkbox and select sites in the box below it.
Shipping Regions (Required) The geographic regions for this
shipping method. For more information, see
Create Shipping Regions.
Price Groups Select the price groups this shipping method
applies to. If you leave this field blank, the
shipping method applies to all price groups.
Shipping Charges (Required) Shipping charges are based on
order cost. You specify one or more cost
ranges and assign a shipping charge to each
range. For example, order totals up to $50
cost $5.95 to ship, order totals from 50.01
to $74.99 cost $9.50 to ship, and order totals
of $75 or more ship for free.
Tip: To create a shipping method that provides
the same shipping cost on all orders (for
example, to offer free shipping), enter a Range
Start value of 0.00, leave the Range End value
blank, and then enter a shipping cost.
Note: An externally priced shipping method
can be created without specifying shipping
charges, provided it is not a fallback shipping
method.

Specify a fallback shipping method

If your store integrates with calculators for shipping services, you can specify internal
shipping methods that will be offered to shoppers when Commerce cannot connect to the
external shipping service, for example, in the event of an outage.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

20-3
 Chapter 20
Specify a default shipping country

The fallback shipping methods are displayed on the storefront during the checkout
process. This prevents errors during order processing and allows orders to progress to
the next step.
You can mark any number of shipping methods as fallbacks. You might want to create
a fallback method for each type of shipping method you expected to receive back from
the external shipping service.
Internally priced shipping methods marked as fallback are returned only if Oracle
Commerce cannot connect to an external shipping service. Externally priced shipping
methods marked as fallback are returned in both cases: The external price and
availability are used if the service responds and internal prices are used if the service
does not respond.
See Integrate with External Shipping Calculators for more information about
configuring when Commerce uses a fallback shipping method.

Specify a default shipping country

You can optionally specify a default country that automatically appears in the shipping
address and appears at the top of the list of available shipping countries .during
checkout.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The shopper can select a different shipping country.

To specify a default shipping country, follow these steps:
1. Click the Settings icon, then select Shipping Methods.
2. Select a default shipping country.
The default shipping country you select must be a country from one of your
enabled shipping methods. Otherwise, the storefront will not display the default
country you selected.

Configure shipping surcharges

You can apply additional shipping charges to products because of size, weight, or
special handling requirements.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The surcharge is a fixed, monetary amount that applies to a specific product. For
example, a kayak can have a shipping surcharge of $25, while a mattress, whose
delivery includes removal of an old bed, might have a surcharge of $75. A product’s
shipping surcharge is the same for each available shipping method.
Shipping surcharges are not affected by shipping promotions and are added to the
order total during checkout, after discounts have been applied. For example, a
shipping promotion offers free ground shipping on all orders over $200. A shopper
purchases a $225 kayak with a $25 shipping surcharge. The order meets the free-
shipping promotion condition, so the $30 ground shipping charge is removed, but
the $25 shipping surcharge remains.

20-4
 Chapter 20
Understand externally priced shipping methods

To configure shipping surcharges, follow these steps:

1. Add the Shipping Surcharges property to the product types that you will use to create
products that require surcharges. Shipping Surcharges is not a required property, so you
can add it to a product type that you will use for other products. See Create and edit
product types for information about adding properties to a product type.
2. Add a shipping surcharge amount when you create or edit a product. You can add the
surcharge manually in the administration interface or by importing product details. See
Create and work with products for information about creating individual products in your
catalog. See Import catalog items and inventory for information about importing new and
updated products.
3. Specify the shipping methods that are available for products that have shipping
surcharges. See Create a shipping method for more information.

Understand externally priced shipping methods

Externally priced shipping methods can be created to represent each shipping method that
can be returned by your shipping calculator service.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This allows you to take advantage of Oracle Commerce’s shipping promotion and tax
calculation features.
Externally priced shipping methods are created in the administration interface and their price
and availability are determined using a combination of internal rules and the shipping
calculator service. During checkout, Oracle Commerce determines which externally priced
shipping methods are available based on internal rules. The available shipping methods and
costs are sent to the shipping calculator service in the request. The shipping calculator
service responds with some or all of the available methods and their prices and these
available shipping methods are displayed to the shopper with the returned price. Oracle
Commerce applies shipping promotions and calculate taxes for externally priced shipping
methods as it does for internally priced shipping methods. See Work with external shipping
methods for more complete information on this subject.
You create an externally priced shipping method through the Shipping Methods page
available from the Settings list. This is just like the existing internally priced shipping method
except there is a selection in the dropdown list to indicate that it is externally priced. Since the
externally priced shipping method is available in the administration interface in the same way
as internally priced shipping methods, this also includes the “applies to shipping methods”
picker in shipping promotions.
Externally priced shipping methods behave the same as internal shipping methods. Shipping
promotions and taxes are applied to externally priced shipping methods the same way as
they are to internal shipping methods. The store recognizes the shipping regions associated
with externally priced shipping methods as it does internal shipping methods. The store
should recognize the shipping regions associated with an externally priced shipping method
that is considered unavailable based on internal rules but is returned by the shipping
calculator. The service overrides the internal rules in this case and the resulting shipping
method/storefront interface behaves the same as all other internal shipping methods. For
more information about webhooks and the Shipping Calculator service, refer to Use
Webhooks.
You can also select “fallback” shipping methods for an externally priced shipping method.
Fallback shipping methods are displayed only if the shipping calculator service fails (or does

20-5
 Chapter 20
Understand externally priced shipping methods

not respond or responds improperly). This gives you the ability to still take orders if the
shipping carrier service is having problems. Refer to Specify a fallback shipping
method for more information on setting up fallback shipping methods. You can also
refer to Integrate with External Shipping Calculators for more information about
shipping calculators and about configuring when Commerce uses a fallback shipping
method.
Note: Externally priced shipping methods are supported in the administration interface
and the Admin API. These methods are not supported in the Agent Console.
Merchants should not create externally priced shipping methods if they need to
support the feature in Agent Console..

Create an externally priced shipping method

To create a new externally priced shipping method in the administration interface,
follow these steps:
1. Click the Settings icon, then select Shipping Methods.
2. Click New Shipping Method.
3. Select Externally Priced from the drop-down list.
4. Enter the information that identifies the new externally priced shipping method.
See Create a shipping method to learn about the information to enter in each field.
For more information on externally priced shipping methods and how they work
differently from other shipping methods, refer to Integrate with External Shipping
Calculators.
5. Click Save.

20-6
21
Configure Wish Lists
This section provides an overview of the wish list features in Commerce.
It describes how to implement and maintain wish lists for your store.

Understand wish list features

Wish lists provide shoppers with the following:

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

• A way to create and manage a list of products they are considering buying. Included is
the ability to save items in wish lists and purchase easily from them later.
• The ability to create and manage multiple wish lists so shoppers can better organize
items they may want to purchase.
• The ability to share their wish lists.
• The opportunity for shoppers to add comments to items in their wish lists.
• A social experience where shoppers can receive feedback and suggestions from friends
and family members they invite to their wish lists.
• Email notifications for key wish list-related activities.
Registered shoppers can participate in a variety of wish list activities, including:
• Creating wish lists with personalized names; the wish list privacy settings can be private,
group, or shared. For more information, see Understand private, group, and shared wish
list privacy settings.
• Viewing up-to-date availability, price, and associated offers for the products included in a
wish list.
• Using an Add to Wish List button or selector on a product details page to choose which
wish list to add the product to; at this point, a new wish list can also be created.
• Adding a product from a wish list to a shopping cart for purchase.
• Editing and deleting owned wish lists.
• As a wish list owner: creating, editing, and deleting posts and comments.
• As a wish list member: adding a comment, deleting his or her comments, and deleting
product posts he or she added along with all associated comments.
• Setting the priority and quantity for each product in a wish list.
• Sorting posts by date added and priority.
• Inviting friends to be a part of a wish list to encourage collaboration and feedback, and
the sharing of products and gift ideas.
• Moving product posts from one wish list to another. When moving the post, the shopper
can also create a new wish list for the post.

21-1
 Chapter 21
Understand wish list features

• Sharing wish list links via Facebook, Twitter, Pinterest, and email.
If the Pinterest icon is not visible on the shopper wish list pages, in the Wish List
layout, upgrade to the newest version of the Wish List Header widget.
• Subscribing or unsubscribing from wish list email notification in his or her
storefront My Account settings. For more information, see Enable wish list email
settings.
• Adding and changing wish list owner profile pictures; the pictures are visible next
to comments made by the owner or member.
• Receiving price change notifications on the product post.
• Email notifications indicating the product price in the currency chosen in the
storefront.
Each shopper profile can have up to 50 wish lists. Each wish list can The number of
product posts, text posts, and comments on an individual post is set to 100 per wish
list.

Understand private, group, and shared wish list privacy settings

A wish list owner can choose to designate a wish list as private, group, or shared.
A private wish list is visible only to the wish list owner.
A group wish list is visible to the wish list owner and people they invite as members.
Owners and members can perform the following tasks in a group wish list:
• View the wish list.
• Add products to the wish list and delete any products they added. Deleting a
product post deletes all its associated comments.
• Comment, delete, and edit their comments on a wish list; in addition, owners can
delete any comments.
A shared wish list can be viewed by anyone who receives a link via Facebook, Twitter,
Pinterest, or email. A wish list owner can share the link to any of their wish lists by
clicking the Share button for Facebook, Twitter, Pinterest, or email. Once a wish list is
shared, anyone with the link, whether logged in or anonymous, can also view the wish
list. However, only members of the wish list can view, comment, delete, and add
products to the wish list.
The link to a shared wish list can be passed on in other ways (for example, via private
email) to other people. Anyone with the link can view the wish list. Members’
comments on a group wish list, as well as their names, become public if the owner
designates the wish list as shared. Oracle strongly recommends you add text to your
Terms of Use notifying your customers about this behavior.
A wish list owner can edit the privacy mode of a wish list at any time. Changing the
privacy setting from Shared or Group to Private makes the wish list viewable only by
the owner.
To edit from Shared or Group to Private, the owner must first delete all members from
the wish list. However, once changed to Private, the wish list content is retained.
Member names are noted as being no longer a member, and a generic profile picture
is displayed.

Share using email, Facebook, Pinterest, or Twitter

To accommodate social sharing on your site, do the following:

21-2
 Chapter 21
Understand wish list features

1. Click the Settings icon, then click Setup.

2. Click the URL Patterns tab.
3. This step is optional if your URL patterns are correctly configured. On the URL Patterns
page, for the Product Page URL, double-click the link in the Value column to open the
New Value dialog. Edit the URL pattern using the available properties.
URL patterns let you customize the URL structure for the different types of pages on your
store. Select a page type and replace the components in the default pattern with values
for a new custom pattern. For more information, see Enter basic store information.
The new value will be applied to your product details pages once you click the check
mark at the top of the dialog. Click the x to cancel.
4. To add the social sharing links to your product details pages, in the administration
interface, click Design.
5. Click the Select Layout tab. Click Product, and then click Product Layout.
6. Click the Grid View tab. In grid view, hover over the Product Details widget, and click
the settings icon.
7. Depending on the types of social sharing you want to make available to your shoppers,
add the following elements to the page:
• To add email, Facebook, and Twitter icon links to product detail pages, add the Social
Sharing element.
• To add email, Facebook, Twitter, and Pinterest icon links to the product detail pages,
add the Social Sharing 2 element.
8. Save your changes
For more information, see Work with layout components.
Shoppers can share a wish list link using email, Facebook, Pinterest, or Twitter by doing the
following:
1. If you have not already done so, set the privacy setting for the wish list to Shared. Make
this change by doing one of the following:
• Click the lock icon (Edit Wish List Settings) under the wish list name.
• Click the Wish list actions arrow at the right side of the page, and click Edit.
Privacy settings are made per wish list. Setting the privacy setting for one wish list does
not affect the privacy setting for any other wish list.
2. On the right-hand side of the page across from the Wish List Owner name, click the
Share by email, Share on Facebook (if available), Share on Pinterest, or Share on
Twitter icon.
If the Facebook icon is absent to your shoppers, you must add a Facebook App Id by
logging into the Commerce administration interface. See Configure Facebook access and
announcements for more information. To display the Pinterest icon, place the latest
version of the Wish List Header widget in the Wish List layout.
3. Follow the instructions to log into the email service, Facebook, Pinterest, or Twitter to
send the link.

Understand localization
Wish lists are localized as a part of the storefront localization. For more information, see
Localize Your Store.

21-3
 Chapter 21
Implement wish lists

Implement wish lists

To use all the functionality of wish lists for your site, it is recommended you complete
the following activities:
• Tailor your wish list appearance to match the rest of your storefront, using the
Design page in the administration interface. For example, wish lists inherit the
global style settings for color, font, and page layout. For more information, see
Design Your Store Layout.
• Add a Facebook App ID.
• Update the Wish List Header widget and Wish List Content widget in the Wish List
layout.
• To include the Pin It on Pinterest icon, on the Product layout, update the Add
Product to Wish List widget. Include the Social Sharing 2 element in the Product
Details widget.
• To have price formatting and currency appear in email notifications, include the
latest version of the Add Product to Wish List widget in the Product layout.
• Enable email settings.
• Update your email templates.
• Edit and use wish list widget content (optional).

Configure Facebook access and announcements

Wish list owners and members can share links to products and invite friends via
Facebook using their Facebook accounts.
To enable the Share Wish List on Facebook and Invite Facebook Friends features for
your shoppers, do the following:
1. Make sure you have a Facebook App ID. To obtain a Facebook App ID, you must
have a Facebook account and register to become a Facebook developer.
Facebook provides information on how to set up your site to allow sharing to
Facebook. For more information, visit [Link].
2. Once you obtain a Facebook App ID, log into the Commerce administration
interface.
3. Click the Settings icon, then select Social Settings.
4. In the Facebook App ID field, enter your ID, and click Save.
5. To configure your Facebook app as a Canvas app, log into your Facebook
merchant account.
6. Create or edit your Canvas app, and enter the URL—[Link]
storefront host name]/facebook/—as the Secure Canvas URL.

Enable wish list email settings

For wish lists to function properly, enable wish list email types in the administration
interface.

21-4
 Chapter 21
Enable wish list email settings

To enable wish list emails, see Configure Email Settings.

Upon initial setup, emails sent by wish lists are text only. However, you can download any of
the wish list email templates, update them, use HTML, and then re-upload them to fit with
your business environment and strategies. For more information, see Customize Email
Templates.
Shoppers can opt to receive email notifications by doing one of the following:
• Click the I want to get email updates check box when creating an account.
• Click My Account > My Details, click Edit and select the I Want to Get Email checkbox.
Click Save. My Wish List Setting is displayed. Under Email Notification Settings, click
Yes for those emails they want to receive.
At any time, shoppers can edit the email notification settings in My Account.
The following table describes the types of email that are available for wish lists:

Email Type Description

Wish List New Comment Sent to all other members of a wish list when a
member adds a comment to a product post. An
email is not sent to the commenter.
Wish List New Member Sent to all current members of a wish list to
introduce a new member; this email is not sent to
the new member.
Wish List New Post Sent to all other members of a wish list when a
new product post is added to the wish list or a
product is moved to an established or new wish
list. If the product is already in the destination wish
list, no email is sent.
A product post is added when a shopper clicks the
Add to Wish List button or selector on a product
details page. An email is not sent to the poster.

Additional notification email template properties

You can optionally use sections to add and organize related content if another section
heading is needed.
Additional properties are available in the wish list notification email templates should you
want to customize your emails. For details about accessing the templates, see Customize
Email Templates.
You can make template changes for the following:
• New comment email
– Wish list owner profile image URL
– Profile image URL of shopper who added a comment
– Product title
– Image URL of the product associated with the comment
– First and last name of the shopper who created the post associated with the
comment
– Full name of the email recipient
• New product post email

21-5
 Chapter 21
Edit wish list widget content

Ensure that the latest version of the Add Product to Wish List widget is added to the
Product layout.
• Current price (list price or sale price as applicable)
• Profile image URL of shopper who added the product; if a profile image has not
been selected, an image called no image is sent.
• Profile image of wish list owner
• Full name of the email recipient
• New member email
• Profile image URL of new member
• Profile image URL of wish list owner
• Full name of the email recipient
Note: If no profile image has been set by the shopper, a generic image URL is
displayed.

Additional email properties

You can add properties to the following wish list email templates:
• Wish List New Comment
• Wish List New Member
• Wish List New Post
See Customize Email Templates to learn how to download and edit email templates.

Edit wish list widget content

Wish list widgets let shoppers create and manage wish lists.

This section applies to Storefront Classic only.

This section describes how to work with storefront classic widgets. To learn how to
configure wish lists with Open Storefront Framework (OSF), see Configure wish lists
for OSF applications.
You can edit any of the following wish list widgets on the Design page in the
administration interface:
• Wish List Content
• Wish List Header
• Wish List Notification Settings
• Wish List Settings
• Wish List Welcome
• Shopper Profile Wish List
The Wish List Welcome widget is useful as it controls content that introduces wish lists
to your shoppers in a way that fits your brand and voice, and encourages customers to
create wish lists. This brand information page is shown to shoppers prior to login.
Once logged in, shoppers see their main wish list page.

21-6
 Chapter 21
Set up wish lists in a multiple site environment

The following layouts are affected by edits to the wish list widgets:
• For the Product Layout, use the Product Details widget, and Add to Wish List Button
element for placement of the button.
• For the Wish List Layout, use the Wish List Welcome widget to include branding and
other site-specific text. Other widgets that affect the Wish List Layout include the Wish
List Invitation, Wish List Welcome, and Wish List Content widgets.
See Customize layout components for details about editing widgets.

Configure Facebook announcements

In a Storefront Classic application, you can make changes to the content of the
announcements your shoppers send to Facebook by editing the associated text snippets.
This section describes how to edit the text snippets in the administration interface.
To view the editable text snippets:
1. On the Design page, click the Developer tab.
2. On the Text Snippets tab, select Social from the drop-down list.
You can change the values for the following keys by clicking the value and editing the new
value field:
• socialFacebookInviteMessageText
• socialFacebookShareProductDescriptionText
• socialFacebookShareWishlistDescriptionText
• socialFacebookShareWishlistTitleText
The default text snippets are translated for all supported languages. If you make changes to
the default text snippets, you must manually translate them into different languages your
store supports. See Customize your web store's text for more information.

Set up wish lists in a multiple site environment

Wish lists are not shared among sites and must be configured on a per-site basis.
If your environment supports multiple sites where wish lists are configured, a registered
shopper can create wish lists on more than one site, but each wish list can be accessed only
from the store where it was created.
Note: When you delete a site, its associated wish list environment is also deleted, along with
its shopper content.
Follow these steps to configure a wish list for an existing site. (To learn how to create a site,
see Define a site.)
1. Click Settings icon, then select Setup.
2. Select a site from the drop-down list.
3. Click Save.
This action connects the site to the Oracle Commerce servers hosting the site wish lists.
4. (Optional) Click the Settings icon, then select Email Settingsto configure the Wish List
New Comment, Wish List New Member, and Wish List New Post email notifications.
For more information, see Enable wish list email settings.

21-7
 Chapter 21
Configure wish lists for OSF applications

Configure wish lists for OSF applications

Commerce includes Open Storefront Application (OSF) widgets that let you add wish
lists to your OSF applications.

This section applies to Open Storefront Framework (OSF) only.

Wish list plug-ins are included with Commerce, but they are not enabled and are not
available by default in the reference application.
This section describes how to add wish list functionality to an OSF application. This
section is intended for developers who want to use OSF to create Commerce
storefront applications. The procedures in this section assume that you have set up a
working OSF development environment and have created an application where you
will add wish lists. For more information, see Understand the Open Storefront
Framework.

Add wishlist package dependencies to your application

Commerce provides a read-only npm (Node Package Manager) registry that you can
access to obtain OSF packages and their dependencies.
1. Navigate to your <workspace-dir>/packages/apps/<appname> folder.
2. Run the following commands:
yarn add @oracle-cx-commerce/wishlist-endpoints
yarn add @oracle-cx-commerce/wishlist-actions
yarn install
3. Ensure wishlist dependencies are installed to your local node_modules/@oracle-
cx-commerce folder.

Add wish list plug-in exports to your application

You must export references that enable the application's endpoints to be accessed
using dynamic imports.
1. Navigate to your <workspace-dir>/packages/apps/<appname>/src/plugins/
actions/[Link] file and add the following line. Make sure this line appears
above default exports:
export * from '@oracle-cx-commerce/wishlist-actions'; //
2. Navigate to your <workspace-dir>/packages/apps/<appname>/src/plugins/
actions/[Link] file and add the following line. Make sure this line appears
above default exports:
export * from '@oracle-cx-commerce/wishlist-actions/meta'; //
3. Navigate to <workspace-dir>/packages/apps/<appname>/src/plugins/
endpoints/[Link] file and add the following line. Make sure this line appears
above default exports:
export * from '@oracle-cx-commerce/wishlist-endpoints'; //
4. Navigate to <workspace-dir>/packages/apps/<appname>/src/plugins/
endpoints/[Link] file and add the following line. Make sure this line appears
above default exports:
export * from '@oracle-cx-commerce/wishlist-endpoints/meta'; //

21-8
 Chapter 21
Configure wish lists for OSF applications

Allow shoppers to move items to a wish list from the cart

Once your OSF application has been built and deployed to the Commerce server
environment, you can use the administration interface's Design page to enable the Move to
Wish list functionality on the Cart page.
1. Log into Commerce and click the Design icon in the main menu. In the top-right corner of
the Design page, you should see a dropdown menu where you can select a deployed
OSF application.
2. Select your OSF application from the dropdown menu.
3. Use the Filter Layouts field to search for the Cart Page layout and then open the Cart
container.
4. Click on Settings icon on the Cart Item Details layout.
5. Click the Move to Wish List checkbox.
6. Publish your changes.

Understand wish list layouts and widgets

The wish list widgets let shoppers create and manage multiple wish lists. The OSF wish list
widgets make use of the Commerce wish list service and interface with the corresponding
Social Wish Lists API endpoints.
The wish list widgets let shoppers do the following tasks:
• Create, edit, and delete wish lists with different privacy settings: Private (Only the owner
can see and add to the list.), Group (Only the owner and people they invite can see,
comment on, and add items to the list.), and Shared (Anyone with a link can see the list,
but only the owner and people they invite can comment on and add items to the list.)
• Add items from a product's Product Details Page to a new or existing wish list. (The
default widgets do not support adding items to a wish list from the Product Listing Page,
but you can extend them in your OSF workspace to add this functionality.)
• Move items from a wish list to the cart or from the cart to a wish list.
• Move items from one wish list to another.
• Edit or delete wish list items.
• Add comments to wish list items.
• Share wish lists with other people via a link or invite them to a wish list, where they can
also edit and comment on the list.
Note: The default widgets do not support sharing via Facebook, Pinterest, or Twitter, or
receiving automatic price change notifications for products in a wish list. Default wish lists
also do not show item availability (stock status). However, you can extend the widgets in your
OSF workspace to add this functionality. The out-of-the-box OSF wish list implementation
also does not currently allow the wish list owner to manage wish list settings.
Commerce includes the following wish list layouts:
• Wish Lists
• Wish List Details
• Commerce includes the following wish list widgets:
• Add to Wish List (Add this to the Product Details container)

21-9
 Chapter 21
Configure wish lists for OSF applications

• Wish List Details

• Wish Lists
• Wish List Breadcrumbs
Detailed information about each widget's code, including actions, selectors, fetchers,
and endpoints, is available in the JS API documentation that you can download from
Oracle Customer Connect.

21-10
22
Localize Your Store
You can translate your catalog and store content into multiple languages so a shopper can
automatically see your store in the language specified by her browser’s locale. A shopper can
also manually select a language from a list of languages your store supports.
This section describes how to translate your store into other languages. For information about
how to display your store’s prices in different currencies, see Configure Price Groups.

Understand store localization

Each language Commerce supports matches an ISO locale. For example, English
(Australian) matches the en_AU locale.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You must assign a default language for each Commerce site you set up. You must create all
catalog items in the site’s default language and then translate them into the additional
languages your site supports. See Prepare your catalog for translationand Import translations
for catalog items for more information about translation. See Enter basic store information for
more information about assigning default and additional languages to a site.
Important: Do not change your site's default language once you set it, especially if you have
already created catalog items like products, SKUs, and collections.
You can translate the values for short-text and rich-text properties for all catalog items. For
example:
• Product names, descriptions, and brands
• Collection names and descriptions
• Variant property names and values. For example, you can translate both the variant
property name Color and all its values, like green, blue, and red.
• Although not part of your catalog, you can translate the shopper-visible properties for
settings, for example, the names of shipping methods and promotions.
You can also translate store text that is not part of the catalog, for example, labels,
messages, and help tips. See Translate store text for more information.
The shopper’s browser locale controls the format of numbers, including dates and prices. You
cannot manually change or customize number, date, or currency formats.
Note: Your store can support more than one currency. For information about selecting a
default currency when you set up the store, see Define additional store settings. For
information about displaying prices in other currencies, see Configure Price Groups.
Emails your store sends are already translated into all the languages that Commerce
supports. You can customize the email text in all the languages your store supports. See
Configure Email Settings for more information. Emails are sent in the language of the
shopper’s browser when the event that triggered the email took place. For example, if a

22-1
 Chapter 22
Select additional languages

shopper places an order from a browser whose locale was set to ES, the service
sends the Spanish translation of the Order Placed email.

Select additional languages

The first step in translating your store is to select the additional languages you want
your store to be displayed in.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Once you select additional languages, a new dropdown list appears at the top of the
administration interface. When you are ready to translate components of your catalog
and store into a new language, select that language from the list before you start
translation tasks.
To select additional languages your store supports:
1. Click the Settings icon.
2. Select Setup from the Settings list.
3. On the Location tab, click the Additional Store Languages field and select a
language. See Languages supported by the storefront for the available options.
Repeat this step for each new language your store will support.
When you remove any of the additional languages, shoppers can no longer select
them from the Language list on your store.
To remove a supported language from your store:
1. Click the Settings icon.
2. Select Setup from the Settings list.
3. On the Location tab, in the Additional Store Languages field, click the X icon in
the corner of the language you want to remove.

Languages supported by the storefront

The following languages are supported for use with Commerce. All languages in the
list are available for use on the storefront translation and search input.
Arabic (ar), Catalan (ca), Indonesian (id), Malay (ms), and Vietnamese (vi) are not
supported for the administration interface.
• Arabic – ar
• Bulgarian – bg
• Catalan – ca
• Chinese (Simplified) – zh_Hans
• Chinese (Traditional) – zh_Hant
• Croatian – hr
• Czech – cs
• Danish – da
• Dutch – nl

22-2
 Chapter 22
Select additional languages

• English (Australian) – en_AU

• English (Canadian) – en_CA
• English (UK) – en_GB
• English (US) – en_US
• Estonian – et
• Finnish – fi
• French – fr
• French Canadian – fr_CA
• German – de
• Greek – el
• Hungarian – hu
• Indonesian – id
• Italian – it
• Japanese – ja
• Korean – ko
• Latvian – lv
• Lithuanian – lt
• Malay – ms
• Norwegian – no
• Polish – pl
• Portuguese (Brazil) – pt_BR
• Portuguese (Portugal) – pt_PT
• Romanian – ro
• Russian – ru
• Serbian (Cyrillic) – sr_RS
• Serbian (Latin) – sr_Latn_RS
• Slovenian – sl
• Spanish – es
• Spanish (Mexico)– es_MX
• Swedish – sv
• Thai – th
• Turkish – tr
• Ukrainian – uk
• Vietnamese – vi

22-3
 Chapter 22
Prepare your catalog for translation

Prepare your catalog for translation

Create all catalog items in your store’s default language and then translate them into
the additional languages your store supports.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Text for a short-text or rich-text properties can be translated when the property is
marked as translatable in the product type. Some properties, such as the Base
product’s Name, Description, and Long Description properties, are marked as
translatable by default. New properties you create are not marked as translatable by
default. When you create new properties you can decide if they will contain
translatable content and mark them accordingly. Once you mark a property as
translatable, you cannot remove that setting. See Create and edit product types to
learn how to mark properties as translatable.
Note: The names of collections and the names of shipping methods are automatically
translatable; there is no setting to mark them as such.

Import translations for catalog items

The easiest way to translate your catalog into the additional languages your store
supports is to export products, variants, and collections in your store’s default
language, replace the translatable strings with localized text in the spreadsheets, and
import them back into your catalog.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

See Import and Export Catalog Items and Inventory for more information.
When you export catalog data for translation, you must select a language that the
export supports. If you select a different language than your store’s default language,
LOCALE appears in the fifth column (cell E1) of the export spreadsheet and shows the
ISO locale code for the language, for example, LOCALE=fr.

When you import the translations back into your catalog, made sure LOCALE appears in
the fifth column (cell E1) of the import spreadsheet and shows the ISO locale format
for the language you are importing, for example, LOCALE=fr.

Note: You cannot create new items when you import translations. All new items, even
those created by import, must be created in your store’s default language.

Manually translate properties

You cannot import translations or other values for shopper-visible settings, such as the
names of shipping methods, so you must manually translate them.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You can also manually translate properties for catalog items, though importing
translations is recommended when working with a large number of properties. See
Import translations for catalog items for more information.

22-4
 Chapter 22
Translate store text

To manually translate items:

1. Select the language to translate to from the content-language list at the top of the page.
2. Open the item whose properties you want to translate.
3. Fields for translatable properties that you have not yet translated into this language are
blank.
Note: The untranslated names of product-type properties are not blank, but appear in the
store’s default language.
4. Enter the translated value for each translatable property on the page.
5. Click Save.

Translate store text

Use text snippets to translate the text displayed on your store into the different languages
your store supports.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Store text includes messages, labels, and help tips. You access and translate your store’s
text snippets on the Design page. See Customize your web store’s text for more information
about translating store text for Storefront Classic applications. See Configure widgets in the
administration interface for information about translating store text for Open Storefront
Framework applications.

Configure the default locale for a site

By default, when a shopper visits an Oracle Commerce site, it displays in the browser's
preferred language if that language supported by the site. You can configure the site to
display in the site's default language, even if it is not the browser's preferred language.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Each language Commerce supports matches an ISO locale. A site's default language is
specified internally by its defaultLocaleId property. To override the browser's preferred
language and display a site in the site's default language, Use the Admin API to set the site
object’s useDefaultSiteLocale property to TRUE. (It is set to FALSE by default.)

Use the updateSite endpoint to modify the useDefaultSiteLocale property on an existing

site. For example:

PUT /ccadmin/v1/sites/100002 HTTP/1.1

Authorization: Bearer <access_token>
x-ccasset-language: en

{
"properties":
{
"useDefaultSiteLocale": "true"
}
}

22-5
 Chapter 22
Create items in the default locale of a site

When you set a site's useDefaultSiteLocale property to TRUE, you must also make
sure the site is using the most recent version of the Header widget and Language
element.
See Configure Sites for more information about using the REST API to work with sites.

Create items in the default locale of a site

In an environment with multiple Oracle Commerce sites, you can configure Commerce
to allow merchandisers and developers to create new products, collections, and
promotions in any site's default language.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

By default, when you to use the administration interface or the API endpoints to create
products, collections, and promotions, the requests include validation that makes sure
the new items are being created in the default locale of the default site. You must then
manually translate these items to other supported languages.
You can, however, use the Admin API saveAdminConfiguration endpoint to configure
Commerce so that it bypasses this validation, allowing the creation of products,
collections, and promotions in the default language of a site instead. The endpoint's
overrideDefaultLocaleValidation property is an array that contains one or more of
the following strings: createProduct, createCollection, and createPromotion.

The following sample request configures Commerce to allow collections and products
to be created in the default language of any site:

PUT /ccadmin/v1/merchant/adminConfiguration HTTP/1.1

Authorization: Bearer <access_token>
x-ccasset-language: en

{
"overrideDefaultLocaleValidation": ["createCollection",
"createProduct"]
}

Use a specific locale code in a REST request

Requests can include the x-ccasset-language header to instruct the endpoint to use a
specific locale code for content returned in the response.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The locale supplied in the header must be supported by your store. (See Select
additional languages for more information.) The API endpoint documentation specifies
if the x-ccasset-language header is required or optional for an endpoint. See Learn
about the APIs for information about accessing the endpoint documentation.

Troubleshoot translation issues

Many common translation issues have workarounds.

22-6
 Chapter 22
Troubleshoot translation issues

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This list describes workarounds for common translation issues.

• If your store supports additional languages but you do not translate all the translatable
shopper-visible properties, the untranslated strings will appear in the store’s default
language. This can result in multiple languages appearing on the same page. For
example, if you translate product names but not descriptions, the name and description
will appear in different languages on the product details page.
• When you select a default language for your store, select a language that specifies a
neutral locale, not one that specifies a region-specific local. For example, select English
not English (United States) or English (Canada). To support region-specific variants
of the default language on your store, add them to the Additional Store Languages list.
See Select additional languagesfor more information.
Note: In this release, there are no neutral-locale options for Chinese or Portuguese. You
must select either Chinese (Simplified) or Chinese (Traditional) for Chinese and
Portuguese (Portugal) or Portuguese (Brazil) for Portuguese.

22-7
23
Configure Price Groups
A price group is a set of price lists (list price, sale price, and shipping surcharge), in a specific
currency, for the products, SKUs, and shipping surcharges in a catalog.
Price groups let you price catalog items (products, SKUs, and shipping surcharges) in
multiple currencies so a shopper can select from a list of currencies your store supports and
see those prices on your store.
If a user does not have access to a price group, the following conditions apply:
• The editors for the price group and its prices are read-only
• Menu options for actions that the user is not authorized to perform may be hidden or
disabled
• Some icons and menu options will change from Edit to View only

Understand price groups

A price group is a set of price lists (list price, sale price, and shipping surcharge) in a specific
currency for all products and SKUs in your catalog.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

When a shopper selects the currency for an active price group, your store displays all
products and SKUs in that price group’s prices. The following illustration shows the currency
selector on a store that lets shoppers choose to see prices in several currencies.

Your Oracle Commerce instance comes with one configured price group, with the currency in
US Dollars. You can edit this price group to give it a name that makes sense for your
environment, for example the name of your store.
If your store supports multiple currencies, create one price group for each currency that you
want customers on your store to be able to see. When your store supports multiple price
groups, one price group is always the default, that is, the group whose currency and prices
are displayed when an anonymous shopper (that is, a shopper who is not logged in) visits
your store. While shoppers can change price groups by selecting a different currency, the
default prices are always displayed when a shopper returns to your store for a new shopping
session.
If your store supports account-based commerce, you can create unique price groups for each
account registered on your store. See Configure Business Accounts for more information.

23-1
 Chapter 23
Understand price groups

If your Commerce instance supports more than one store or site, you can create
unique price groups for each site that runs on your instance. See Run Multiple Stores
from One Commerce Instance for more information.
If your store supports a loyalty-points program, you use the Admin REST API to create
a currency for loyalty points. Then you create and activate a price group for the points,
just as you would any other currency your store supports. See Create a custom
currency for loyalty points for details about creating a currency for loyalty points and
assigning it to a price group.
Price groups are independent of the languages customers can view your store in. For
example, if you translate your store into Japanese, but do not add a price group that
shows prices in Yen, shoppers can view the store in Japanese but the prices remain in
US Dollars. For information about how to translate your store into other languages,
see Localize Your Store.
To create a new price group:
1. Create a new price group. See Create and edit price groups.
2. Add prices to each product in your catalog for the new price group. See Manually
add prices to products and SKUs and Import prices for products and SKUs.
3. Activate and display the price group. Optionally, make it the default price group so
that its prices are the ones shoppers automatically see when they first visit your
store. See Activate price groups.
4. Publish your changes so they will appear on your store. See Publish Changes.
If direct price editing is enabled for your Commerce store, any price changes you
make are available on the storefront without publishing. See Update prices without
publishing for more information.

Understand how price groups affect promotions

If your store uses price groups to support multiple currencies, you can specify that a
promotion applies only to items purchased in specific currencies. For example,
suppose you create a price group called GBP that lets shoppers view prices in British
Pound Sterling. You can then create an order discount called “Spend £100, get £10
off” that applies only when a shopper displays your store’s prices in British Pound
Sterling and then purchases £100 worth of merchandise. See Understand currency-
specific promotions for more information.

Understand how price groups affect shipping methods

If your store uses price groups to support multiple currencies, you can specify that a
shipping method applies only to items purchased in specific currencies. For example,
suppose you create a Ground Shipping method that is valid only for delivery to the
continental USA. In addition to specifying the appropriate shipping region, you might
also want to make sure that the shipping method is available only when a shopper
displays your store’s prices in the default currency, US Dollars. See Configure
Shipping for more information.

Understand how to use price groups with loyalty programs

If your store supports a loyalty program, you use the Admin REST API to create a
currency that represents loyalty points. Then you create and activate a price group for
the points, just as you would any other currency your store supports. See Work with
Loyalty Programs for details about creating a currency for loyalty points and assigning
it to a price group.

23-2
 Chapter 23
Create and edit price groups

If your store uses one of the built-in tax-processor integrations (Avalara AvaTax or Vertex O-
Series), you can use the REST Admin API to convert the value of points-based orders to
monetary currency so that your tax processor can calculate taxes for the order. (See Work
with Loyalty Programs for more information.) or you can turn off tax calls for the points-based
price group and make sure tax processing is handled externally, for example, in your order
management system. (See Create and edit price groups for more information about
configuring tax settings for price groups.)

Create and edit price groups

A price group is a set of prices in a specific currency for products and SKUs in your catalog.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

To create a new price group:

1. On the Catalog page, click Manage Catalogs and select Price Groups.
2. On the Price Groups page, click the Price Group button.
3. Enter values for the price group’s properties.
4. Click Save.

Property Description
Name (required) Short, descriptive name that identifies the price
group. This name does not appear on your store.
Each price group name must be unique within
your store.
ID (required) The ID that identifies the price group internally.
Each price group ID must be unique within your
store. Even after you delete a price group, you
cannot assign its ID to another price group.
Inherit prices from Use the drop-down menu to select a price group.
This associates the new price group with an
existing price group, creating a price group
hierarchy. Prices from the new price group, or the
child price group, will be inherited from this parent
price group. See Work with price group inheritance
for more information.
Currency The ISO currency associated with the prices in
this price group.
If you created a custom currency for loyalty points,
that currency is also available to assign to a price
group. See Create a custom currency for loyalty
points for more information.

23-3
 Chapter 23
Create and edit price groups

Property Description
Tax Calculation Select one of the following options to specify
whether calls are made to your tax processor for
this price group:
Calculate tax: Commerce calls the tax processor
your store integrates with, which calculates and
returns tax for prices in this price group. This
option is selected by default.
Do not calculate tax: Commerce does not call the
tax processor your store integrates with and no tax
is calculated for prices in this price group.
This setting affects tax calculation only if your
store uses one of the built-in tax-processor
integrations (Avalara AvaTax or Vertex O-Series),
or an external tax-processor integration configured
with the REST API. If you turned off tax calculation
by selecting None as the tax processor on the Tax
Processing settings page, Commerce will not
calculate taxes for a price group, even if you select
Calculate tax here. See Configure Tax Processing
for more information.
Status Indicates if the price group is active.
Require all products to be in this price group. Select this option to require that every product in
your catalog has a corresponding list price in this
price group before it can be activated. This option
is selected by default and must be selected for the
default price list.
Include tax in the prices Select this option to display all prices in the price
group with tax (for example, VAT) included.
The prices you assign to a tax-inclusive price
group must already include a tax amount. If prices
include tax, your integrated tax processor back-
calculates taxes for each order. That means that
when the call is made to the tax processor when
the cart is priced, no tax is returned.
Once you save a price group with this option
selected, you cannot change this setting.
If you select this option, you may also need to
configure additional settings on your tax
processor. See Configure Tax Processing for more
information.

Edit price groups

Once you create a price group, you can change is its name. You cannot change its ID
or the currency associated with it.
To edit a price group:
1. On the Catalog page, click Manage Catalogs and select Price Groups.
2. On the Price Groups page, click the name of the price group to edit.
3. Enter a new name.
4. Click Save.

23-4
 Chapter 23
Manually add prices to products and SKUs

Delete price groups

To remove a price group from your system:
1. On the Catalog page, click Manage Catalogs and select Price Groups.
2. On the Price Groups page, click the name of the price group to delete.
3. Click Delete.

Manually add prices to products and SKUs

You can manually add prices to products and SKUs by updating either your catalog or the
price group itself.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

To add prices to individual items in your catalog, display the details page for a product and
click the Price Groups tab. See Create and work with products for information about adding
prices to a product or SKU.
To add prices to the price group, display the details page for a price group and click the
Products link. A list of all products and SKUs in your catalog appears. You can add or change
the list price, sale price, or shipping surcharge for products or SKUs in the list. See Activate
price groups for information about displaying a price group’s details.

Format prices
When entering prices, keep in mind that the locale of the browser you use to access the
Oracle Commerce administration interface controls number format and the price group’s
currency controls the precision specifier (the number of decimal places) in the prices
shoppers see on your store. For example, suppose your browser’s locale is US_EN and you
are adding prices for a price group whose currency is Japanese Yen (JPY). If you enter a
price as 1240.89, Oracle Commerce displays the price as 1,241 because Japanese Yen does
not display decimal places.

Import prices for products and SKUs

The easiest way to add prices to products and SKUs is to export products and, if applicable,
SKUs, add prices for each price group to the spreadsheet, and import them back into your
catalog.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

See Import and Export Catalog Items and Inventory for more information.
When you look at the exported spreadsheet, you can see that the second row displays
column headings that contain the internal names of the exported properties. Each price group
has three column headings:
• PLG:<id>[Link]
• PLG:<id>[Link]
• PLG:<id>[Link]

23-5
 Chapter 23
Activate price groups

In each column heading, <id> is the ID for the price group. For example, the column of
list prices for the default price group has the heading
PLG:[Link].

Prices for the products or SKUs begin in the third row and continue for the remainder
of the spreadsheet. If an item does not have a value for a property, the corresponding
cell is blank.
Keep the following in mind when you import prices:
• Price groups are not dependent on languages (ISO formats) you may translate
your store into. Therefore, when you import prices into your catalog, the LOCALE
that appears in the fifth column (cell E1) of the import spreadsheet has no effect
on the imported prices.
• If you create a new product via import, it must include a list price for each price
group in your catalog, even for price groups that are not yet active.
If you have configured price list group inheritance, note that when you export a product
or SKU whose price is inherited from a parent price list group, the prices will display in
the spreadsheet as null.

Activate price groups

Activating a price group makes its prices available to be displayed on your store.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Once a price group is active, you can add it to your store. Then shoppers can select a
currency from a list of active currencies that appears at the top of each page of your
store. Each currency in the list is associated with an active price group you chose to
display.
Note: If your store supports account-based commerce, you can assign active price
groups to accounts so logged-in contacts can see those prices. See Configure
Business Accounts for more information.
To activate a price group:
1. On the Catalog page, click Manage Catalogs and select Price Groups.
2. On the Price Groups page, select the price group to activate.
3. Once the price group page is displayed, click the Activate button to activate.
4. Click Save.
5. To display prices from an active price group, add it to your store. See Display
active price groups for more information.
If your catalog contains products when you create a price group and you chose to
force the price group to include all products in your catalog, you cannot activate that
price group until it contains list prices for all products and SKUs in your catalog. If you
try to activate a price group and see an error message that says the group does not
contain list prices for all your products, check to see which products do not have prices
in the price group. You can check for missing prices in the following ways:
• Click the Products link on the price group’s details page to see products and their
prices. By default, all products are displayed. To show only products that do not

23-6
 Chapter 23
Update prices without publishing

have list prices, select Show Only Products With No Prices from the dropdown list in
the upper-right corner of the page. Then add the missing prices.
• Export all the products in your catalog. When you view the spreadsheet, you can easily
see which products do not have list prices assigned from each price list.
For more information about adding missing prices, see Manually add prices to products and
SKUs and Import prices for products and SKUs.

Display active price groups

Activating a price group does not automatically add it to your store. To display an active price
group on your store, you must add it to your store’s Setup settings. You can also change the
default price group on the Location tab of your store’s Setup settings page.
To display active price groups on your store:
1. Click the Settings icon.
2. Select Setup from the Settings list, then click the Location tab.
3. To change the default price group, select a price group from the Default Price Group
drop-down list.
Only price groups that include a list price for every product in your catalog are eligible to
be the default price group.
4. To display an additional active price group that shoppers can select, add it to the
Additional Price Groups field.
To stop displaying a price group on your store, remove it from the Additional Price
Groups field.
Note: Price groups you add to the Additional Price Groups field can be seen and
selected by all shoppers who visit your store. If your store uses account-based commerce
and you have created price groups to associate only with specific accounts, do not select
those price groups here. See Configure Business Accounts to learn how to display an
active price group only to logged-in contacts from a specific account.
5. Click Save.
6. Publish your changes. See Publish Changes for more information.
If direct price editing is enabled for your Commerce store, any price changes you make
are available on the storefront without publishing. See Update prices without publishing
for more information.

Update prices without publishing

By default, when you create or modify product prices, the changes you make must be
published before they take effect. You can optionally configure Oracle Commerce to make
price changes directly on the storefront without publishing.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Publishing price changes works well for many merchants, particularly those that change their
prices relatively infrequently. Some merchants, however, have a large number of products
and change their prices frequently, in some cases updating prices several times a day. For
these merchants, Oracle Commerce provides the ability to make price changes available on
the storefront immediately, bypassing the publishing process.

23-7
 Chapter 23
Work with price group inheritance

To enable this feature, you use the updateDirectPriceEdit endpoint. For example:

PUT /ccadmin/v1/merchant/directPriceEdit HTTP 1.1

Authorization: Bearer <access_token>
Content-Type: application/json

{
"enable": true
}

Note that if your stores have any unpublished price-related changes, you must publish
them before attempting to set enable to true, or the call will fail.

Use direct price editing

When direct price editing is enabled, if you create or modify a product (in the
administration interface, using an endpoint, or through an import process), price
changes you make are available on the storefront without publishing; they do not
appear in the list of changes that are returned by REST endpoints or appear in the
Publishing page of the administration interface. Other product changes, however,
must still be published. As a result, prices may exist on your production system before
the associated products do. These prices will be applied to the products when they are
published.
When you publish changes, Oracle Commerce initiates an indexing operation so the
search index is updated to reflect the changes. With direct price editing, though, prices
on the production server can be changed without publishing, which means prices in
the index may become out of date. To ensure the index is kept up to date, enabling
direct price editing also sets up a schedule to perform incremental indexing every 15
minutes. However, if you have already used the setSearchPartialSchedule endpoint
in the Search Data and Indexing API to set up a different incremental indexing
schedule, then that schedule will remain in place instead.

Disable direct price editing

You can disable direct price editing by using the updateDirectPriceEdit endpoint to
set the enable property back to false. Doing this initiates publishing of all pending
changes.
Note, however, that you should decide which mode makes sense for your stores, and
continue to use it unless your business needs change. The feature is not designed to
be turned on and off frequently. Disabling direct price editing may cause a
considerable delay, because Oracle Commerce must then synchronize your publishing
server with the prices on your production server.
Disabling direct price editing also cancels the incremental indexing schedule that was
set up when direct price editing was enabled. However, if you used the
setSearchPartialSchedule endpoint to create a different incremental indexing
schedule, disabling direct price editing does not cancel that schedule.

Work with price group inheritance

You can create parent-child relationships with price groups, which allow price groups
to inherit prices for list, sale and shipping surcharge prices.

23-8
 Chapter 23
Work with price group inheritance

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Price groups specify list prices, sale prices and shipping surcharge prices. Using price group
inheritance allows you to define some customer-specific prices for some products and SKUs,
while the rest of the prices are inherited from another price group. This feature is applicable
for both consumer-based and account-based environments.

Understand price group hierarchy

When you create a new price group, or edit an existing one, you can specify a price group
from which to inherit prices. When you save a price group that inherits prices, known as a
child price group, any prices that are not explicitly specified in the child will be inherited from
the group you identify, known as the parent price group. Whenever you make a change in the
parent price group, the changes will be reflected in any inherited prices in the child price
group. For example, if you create a sale price in a parent price group, any children that inherit
the sale price will reflect the price you created in the parent price group. The currency, the
setting for tax calculation and the setting that determines if the SKU prices include tax are
also set from the parent price group. Note that these settings cannot be changed once a price
group is created. When choosing a new parent for an existing price group, your choices are
limited to those price groups whose settings for these properties are the same as the existing
price group.
Although child price groups can have only one unique parent price group, parent price groups
can have more than one child. While child price groups may also have their own child price
groups, the limit for the depth of price groups is three levels. Each price in a child price group
is inherited unless the inherited price is overridden by a price that is explicitly added to the
child.
Note that it is possible for a product or a SKU in a child price group to have a sale price that
is greater than or equal to a list price. This may occur because one or both of the prices is
inherited and sale price validation does not occur on child price groups when a change is
made to its parent.
You can override the inherited list, sale, or shipping surcharge price for a product or SKU.
Note that a SKU can inherit its price from its product or from the parent price group. Should a
SKU price be empty in a child price group, the system will search for, and display a price by
checking for the product price in the current price group, followed by the SKU price in the
parent, and then repeating this sequence for increasingly higher levels of the price group. If
no price is found, then the SKU price is marked as "None defined". A product or a SKU in a
child price group must either have an inherited price or an explicitly specified override price. If
you leave the price empty, it will be inherited. Therefore, there is no way to specify that the
product or SKU has no price in the child price group, assuming that it has a price somewhere
in the hierarchy above.
Note: If you are using Admin APIs to obtain product prices, for a SKU that does not contain a
price in a child price group, the API returns the inherited price, if any; otherwise it returns an
empty price.

Create a new price group hierarchy

To create a price group hierarchy, use the Catalog button in the administration interface. For
additional information on creating and editing price groups, refer to Create and edit price
groups:
1. Use the drop-down menu to select Price Groups.
2. Click the Create New Price Group button.

23-9
 Chapter 23
Work with price group inheritance

3. Provide the name, ID as usual.

4. Select the Inherit prices from check box. Use the drop-down menu to select the
parent Price Group.
5. Select the rest of the options as needed. Note that the Require all products to be
in this price group checkbox means that every product must have an explicitly
specified list price in the price group. For the purposes of this checkbox, an
inherited price would not be sufficient. For this reason, this flag is always set to
false in a child price group.
6. Click the Create button to save the new price group.
You need to activate your price group for prices to be displayed on your store. Child
price groups can only be active if the parent is active. Parent price groups cannot be
deleted. For information on activating price groups, refer to Activate price groups.

23-10
24
Use Volume Pricing for Products
Many companies offer discounts to people who purchase products in volume.
Commerce supports this type of pricing for the products in your catalog. This section provides
details on how volume pricing is specified for a product as well as information on how to
make sure volume pricing appears correctly on your storefront.

Understand volume pricing

You can specify volume pricing for a product in two ways, bulk pricing or tiered pricing.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

For bulk pricing, the same price is applied to the entire quantity of a product that is purchased
but that price is determined by where the quantity purchased falls within the volume pricing
structure. For example, consider the following volume prices:
1 – 10, $2.00
11-20, $1.90
21 – 50, $1.80
51 – 200, $1.70
If a shopper purchased 25 units of this product, the bulk price for the product would fall into
the 21 – 50 level of the pricing structure, making the bulk price for this product calculate to 25
units at $1.80 each.
For tiered pricing, the price of the product changes based on the quantity purchased within
each level of the pricing structure. For example, using the same volume pricing structure
above, if a shopper bought 25 units of this product, the tiered price would be calculated as
follows:
10 units at $2.00 (for the 1 – 10 level)
10 units at $1.90 (for the 11 – 20 level)
5 units at $1.80 (for the 21 – 50 level)

Add volume prices to a product

You can specify volume prices for both the list price and sale price for a product.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Volume pricing can be used in any combination for the list and sale prices, for example, you
can specify volume pricing for both the list and sale prices, or for only the list price, or for only
the sale price.

24-1
 Chapter 24
Display volume pricing in a storefront

To specify a volume price for a product:

1. Access the price group that contains the product. For details on how to do so, see
Edit price groups.
2. Click Products to view the products assigned to a price group.
3. Locate the product whose price you want to specify and click its Edit button. You
see the Edit Price dialog box where you can specify the List Price and Sale
Price for the product.
4. Enable the Volume option for the price you want to edit.
5. Specify whether the price you are defining is a bulk price (same price for all units
ordered) or a tiered price (different prices for the units ordered, depending on the
level of the pricing structure).
6. Define your volume pricing structure:
• Enter a price for the lowest quantity level (currently, 1 and up).
• Click the Add button to add a new level.
• Enter the Range Start value and price for the new level. (Note that the Range
End value for the previous level is automatically filled in, based on the starting
value for the new level. For example, if the new level has a starting value of
11, the previous level is automatically filled in with an ending value of10. This
creates two levels, 1 – 10, and 11 and up.)
• Add additional levels as necessary.
• If you need to remove a level, click its Remove button.
• When you are finished defining the volume pricing structure, click Save.
7. Publish your changes to the storefront. See Publish Changes for details.
If direct price editing is enabled for your Commerce store, any price changes you
make, including adding volume prices, are available on the storefront without
publishing. See Update prices without publishing for more information.

Display volume pricing in a storefront

In order to display volume pricing in a storefront, you must use the set of widgets and
elements that are volume-pricing enabled.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This section describes those widgets and elements and the layouts that use them.
Note that Oracle recommends that you create clones of the out-of-the-box layouts and
modify them to add volume pricing. This keeps the out-of-the-box layouts in their
original form and available for future cloning and modification.
To add volume pricing to the Product Layout:
1. On the Design page, clone the Product Layout, give it a descriptive name,
enable the Make Default Layout option, and save the clone.
2. Go to Grid View for the layout and modify the Product Details widget to include
the Volume Price element. This adds a table similar to the following to the layout,
which displays the volume pricing using columns for quantity and price and rows
for each level of pricing:

24-2
 Chapter 24
Understand volume price display in a product listing

To add volume pricing to the Order Details Layout:

1. On the Design page, clone the layout, give it a descriptive name, enable the Make
Default Layout option, and save the clone.
2. Go to Grid View for the layout, remove the instance of the Order Details widget and
replace it with an instance of the Order Details with Additional Info widget.
To add volume pricing to the Order Confirmation Layout:
1. On the Design page, clone the layout, give it a descriptive name, enable the Make
Default Layout option, and save the clone.
2. Go to Grid View for the layout, remove the instance of the Order Details widget, and
replace it with an instance of the Order Details with Additional Info widget.
To add volume pricing to the Cart Layout and Cart Layout with Shipping layouts, you must
upgrade the Shopping Cart widget used on those layouts to the latest version. If you have not
modified the Shopping Cart widget, this is a simple matter of removing the existing instance
of the widget and replacing it with the latest version. If you have modified the Shopping Cart
widget, see Upgrade deployed widgets for details on upgrading an already deployed widget
in Commerce.

Understand volume price display in a product listing

No modifications are necessary to add volume pricing to the Product Listing widget that can
be included on the Collection Layout and Search Results Layout.

This section applies to Storefront Classic only.

If volume prices are available for a product, they will be taken into account in the product
listing. The highest price (that is, the price associated with the smallest quantity purchased) is
used for the product listing.
Depending on the configuration of a product, the prices displayed in a product listing can take
several forms, an example of which is shown below.

24-3
 Chapter 24
Understand volume price display on the Product Layout

In this illustration, the following prices are displayed:

• Watch
This product has two variant child SKUs. One child SKU has a volume price
whose highest value (lowest quantity) is $60.99. The other child SKU has a
volume price whose highest value of $62.99. The product listing displays $60.99
- $62.99 for the price.
• Brief Case
This product has a single non-variant child SKU. The child SKU has a volume
price whose highest value is $49.99. The product listing displays $49.99 for the
price.
• Clock
This product has a single variant child SKU. The child SKU has one volume price
set in the list price list and another set in the sale price list. The highest value in
the sale volume price is $60.99. This is displayed in red as the sale price. The
highest value in the list volume price is $62.99. This is displayed in the product
listing as the non-sale price, that is, “Was $62.99.”
• Lantern
This product has two variant child SKUs. One child SKU has a simple list price
of $29.50 and the other child SKU has a volume price whose highest value
is $62.99. The price is displayed as $29.50 - $62.99.

Understand volume price display on the Product Layout

The behavior of the volume price table on the Product Layout is dictated by the type of
product being displayed.

This section applies to Storefront Classic only.

24-4
 Chapter 24
Understand volume price display on the Product Layout

Product with a single, non-variant SKU

In this case, the volume price table shows the prices for the single, non-variant SKU.
Because it is a non-variant SKU, no other pickers, such as color or size, are displayed.

Product with a single, variant SKU

In this case, the volume price table is shown for the single, variant SKU. Other pickers are
displayed; however, choosing values from them does not alter the volume price table.

Product with multiple, variant SKUs

For a product with multiple, variant SKUs, there are several scenarios, described below.
Multiple, variant SKUs use the same volume price values
In this case, the volume price table is displayed for all SKUs but it does not change when a
SKU variant is selected.
Multiple, variant SKUs use different volume price values
Your catalog may include a product with multiple, variant SKUs that use different volume
price values, for example, SKU 1 uses volume price scheme A and SKU 2 uses volume price
scheme B. In this case, the volume price table changes depending on the SKU that is
currently selected on the Product Layout page.
Some SKUs use volume pricing and some do not
In this case, the volume price table is only displayed when a SKU is selected that uses a
volume price.

Product with a single SKU and both list and sale prices
For a product with a single SKU that has both list and sale prices, the sale price always takes
priority and the volume price table is rendered when the sale price is specified using volume
pricing. To break it down further, there are several scenarios:
• The single SKU has volume prices set in both the list and sale price lists. In this case, the
volume price table is displayed but it is populated with the prices specified in the sale
price list.
• The single SKU has a volume price set in the list price list and a non-volume price set in
the sale price list. In this case, the volume price table does not appear on the Product
Layout; only the non-volume sale price is rendered.
• The single SKU has a non-volume price set in the list price list and a volume price set in
the sale price list. In this case, the volume price table appears on the Product Layout and
contains the sale volume prices.

24-5
25
Publish Changes
Most items that you create or change in Commerce do not appear on your store until you
publish them. The topics in this section describe the publishing process.

Understand publishing
Commerce saves publishable changes to named worksets. When you want to publish
changes, you publish the workset that contains them. You can publish the changes in all
worksets at once, or you can pick a specific workset to publish.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This section provides details about how Commerce handles publishable changes. See
Understand worksets to learn about how Commerce uses worksets to organize those
changes.
Keep the following points in mind as you prepare to publish changes:
• Commerce does not use versioning for items you edit and publish. There is only one
version of each item in your system.
For example, a merchandiser changes the long description and list price of a product and
then saves his changes but does not publish the workset they are saved in. Later that
day, his manager changes the product’s list price again, saves her changes to the same
workset and then publishes the workset. The most recent changes to the product—the
merchandiser’s long description and the manager’s list price—are published.
Similarly, a single item can be saved to multiple worksets. In this case, the most recent
changes to the item, no matter which workset they are in, get published first. Looking at
the previous example, suppose the merchandiser saved a product’s new long description
and price list in #julyWorkset and then his manager changed the product’s price list again
and saved the change in #default. No matter which of these worksets is published first,
the result is the same: the merchandiser’s long description and the manager’s list price
are published. Then Commerce removes the product from the workset that has not yet
published.
When you save changes to a publishable item in the administration interface, Commerce
warns you if you another user saved changes to the item while you were editing it. For
example, a merchandiser opens a product for editing and changes the long description
and list price. While she is editing the product, her manager opens the product, changes
the list price, and saves those changes. When the merchandiser goes to save her work,
Commerce notifies her that someone else made changes to the item while she was
editing it. She can choose to proceed saving and overwrite her manager's changes,
continue editing the item, or discard her changes.
• You cannot roll back or undo published changes.
• Some changes do not need to be published, and take effect on your production server as
soon as you save them. These changes are described later in this topic.
• Some changes must be published together to maintain the integrity of their relationships.
These changes are described later in this topic.

25-1
 Chapter 25
Understand publishing

• While changes are being published, you cannot work with any publishable items in
the administration interface. Commerce displays a Publish in Progress message
dialog to inform you of this state.
Although you cannot use the administration interface, programs that implement the
Commerce REST APIs might still attempt to update endpoints while changes are
being published. During a publish operation, Commerce responds to all PUT or
POST calls to endpoints that update publishable resources with HTTP status code
503, Service Unavailable.
• You can use the Commerce REST API to download information about recently
published worksets. This can help you keep track of which changes were
published. See Publish changes using the REST API for more information.

Changes that do not require publishing

Not all changes you make are added to worksets for publishing. Some changes made
in the administration interface take effect on your production storefront as soon as you
save them. Some changes are automatically published during the next publish.
The following types of changes take effect as soon as you save them and are not
added to worksets for publishing. Commerce lets you know you are making these
types of changes by displaying a message in the changes tracker. See Understand
worksets for more information.
• Shopper settings, such as changes to the password policy.
• Access control settings, such as changes to internal user profiles.
• Inventory updates.
• Account settings, for stores that support account-based commerce.
• If direct price editing is enabled for your Commerce store, any price changes you
make are available on the storefront without publishing. See Update prices without
publishing for more information.
• If direct catalog editing is enabled for your Commerce store, any catalog changes
you make are available on the storefront without publishing. See Edit catalog items
without publishing for more information.
The following types of changes are automatically published with the next workset or
full publish that happens after they are saved. Commerce lets you know you are
making these types of changes by displaying a message in the changes tracker. See
Understand worksets for more information.
• Search settings, like index fields. Search settings to not appear in any workset
changes list.
• Certain changes you make to the catalog, such as creating a new product type or
changing a price list group, appear as a single item called Catalog Configuration.
The Catalog Configuration item appears at the top of the changes list in every
workset until it is published.

Understand dependencies
Some Commerce items must be published together to maintain the integrity of their
relationships. For example, if you update the description of a shipping method,
Commerce must also publish the method's associated shipping regions, even if you
did not make any changes to them. When you save changes to the shipping method,
Commerce calculates the appropriate dependencies (the associated shipping regions)
and also adds them to the same workset as the shipping method you saved.

25-2
 Chapter 25
Understand worksets

Additionally, Commerce performs a final check before publishing a workset and displays
dependencies that are not already in the changes list on the workset's Review and Schedule
page. This list is populated by changes to dependencies that are saved in two different
worksets. Consider the shipping method example described above. Both the shipping method
and its associated shipping regions added to the same workset. But before that workset is
published, suppose another user saves changes to one of the associated shipping regions in
a different workset. The shipping method whose changes are saved in the first workset is not
automatically added to the changes list in the second workset. But when the second workset
is published, Commerce displays the shipping method as a dependency on that workset's
Review and Schedule page.

Understand worksets
A workset is a named group of changes that are published together. When you want to
publish changes, you publish the workset that contains them. You can publish the changes in
all worksets at once, or you can pick specific worksets to publish.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Worksets help you organize changes so you can more easily track and publish related items
together. For example, suppose you are working on a holiday campaign that you want to go
live at the end of November. You can create a workset called #holidayPromotions. Then,
users who work on Commerce items that support the campaign, like promotions, and SKUs,
collections, and layouts, can save their changes to this workset. Then, the workset can be
published at a pre-scheduled time.
Commerce includes one workset, named #default. If you do not create any other worksets,
Commerce automatically saves all publishable changes to #default.
When you save a change to a publishable item, Commerce automatically saves it to the
active workset. If your Commerce environment includes multiple worksets, you can save your
changes to a different workset or move saved changes from one workset to another, but all
changes that require publishing are saved in at least one workset. There is no way to publish
items outside of a workset.
Some Commerce items must be published together to maintain the integrity of their
relationships. For example, if you update the description of a shipping method, Commerce
must also publish the method’s associated shipping regions, even if you did not make any
changes to them. When you look at the workset that includes the shipping method, you will
notice that it also contains the associated shipping regions. If you move the shipping method
to a different workset, Commerce automatically moves the associated shipping regions.

Understand who can create and publish worksets

Commerce administrators control each internal user's access to specific administration
interface pages and tasks with roles and privileges. Only users who have the Publishing
privilege assigned can create and publish worksets.
Any user who can edit Commerce items, such as catalogs, can view their changes in the
workset that contains them, and can move their changes to a different existing workset.
For more information about privileges, see Understand role-based access control.

25-3
 Chapter 25
Save changes to worksets

Save changes to worksets

When you log into the administration interface, you see the Changes tracker at the
bottom of the main menu.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The Changes tracker is displayed only to users whose profiles allow them to edit
publishable items. For example, a user who can edit catalog items will see the tracker
but a user who can edit only accounts will not see it.
The information the tracker displays changes, depending on where you are working in
the administration interface. See Understand publishing for more information about
these kinds of changes.:
• When you navigate to a page where changes are always included in the next
publish, the changes tracker displays the active workset as paused and notifies
you that changes you make go live at the next publish.
• When you navigate to a page where changes do not require publishing, the
changes tracker displays the active workset as paused and notifies you that
changes you make go live as soon as you save them.

Create and edit worksets

One default workset (named #default) comes with Commerce. Until you create your
own worksets, all publishable changes are automatically saved in this default workset.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Remember that before you can create worksets, your Commerce user profile must
have the Publishing privilege assigned. (See Understand who can create and publish
worksets for more information.) All administration interface users who can access the
Changes page can see all worksets, no matter who created them.
To create a workset:
1. On the Changes page, click Publishing Schedule.
2. Click Add to Schedule and select New Workset.
3. Enter a name for the workset.
The name can be up to 25 characters long and can contain only letters, numbers,
hyphens (-), and underscores (_).
Although not required, it is a good idea to assign unique workset names to make
them easier to identify.
Once a workset is created, you cannot change its name in the administration
interface, though you can change it with the Admin REST API.
4. Click Create.
The new workset appears in the publishing schedule, marked as Not Scheduled.
Commerce adds a # symbol to the beginning of the name of every workset.

25-4
 Chapter 25
Create and edit worksets

Specify the active workset

Your changes are automatically saved in the active workset. Creating a new workset does not
automatically make it the active workset. To make your new workset the active workset,
select it from the Active Worksets dropdown list at the top of the Changes page.

Move items to a different workset

You can move items from one workset to another, though you cannot simply remove them
from their current workset without specifying a new home for them. If an item has
dependencies, they are automatically moved to the other workset. To move items to a
different workset:
1. On the Changes page, select a workset from the Active Workset dropdown list.
2. Select individual items to move or click the Select Page icon to select all the items in this
workset.
See View changes in a workset to learn how to sort and filter a workset to more easily
find items to select.
3. Click the Move button.
4. Select a workset to move the changes to and then click Move.

Delete a workset
You can delete only empty worksets. If you want to delete a workset that contains items,
Commerce lets you select a new workset for them during the delete process. If you delete the
active workset, the #default workset automatically becomes the active workset. You cannot
delete the #default workset.
1. On the Changes page, click Publishing Schedule.
2. Click the Delete Workset icon for the workset. If the workset is empty, simply confirm that
you want to delete it.
3. If the workset contains changes, select a workset to move them to and then click Delete.
Keep in mind that Commerce automatically deletes a workset (except #default, which is
never deleted) once its contents have been successfully published.

View the contents of a workset

To see the contents of the active workset, click it in the Changes tracker. Commerce displays
the workset on the Changes page. To see the contents of a different workset, select it from
the Active Workset dropdown list.
Each item in the workset list displays an icon you can click to see details about when
changes were made and who made them:
• If only one author has made changes, the author's avatar appears in the icon.
• If two or more authors have made changes, the icon displays the number of authors.
Click the icon to see the names of authors who saved changes to the item since it was last
published, as well as the date and time each change was made.
If an item is a member of more than one workset, the item also displays the number of
worksets it belongs to. Click this link to see a list of all the worksets the item belongs to. See
Understand worksets for more information about how Commerce publishes items that are in
multiple worksets.

25-5
 Chapter 25
Schedule publishing

Filter and sort items in a workset

The filtering features let you display a subset of a workset's items. Sorting lets you
display items by date, from either newest or oldest. Filtering items in a workset is
useful for tasks like selecting items to move to a different workset. However, filtering
does not select specific items to publish; all items in a workset are published when that
workset is published.
Select the Filter By check boxes along the left-hand side of the page to find specific
types of items and changes in the workset. Filter By options include:
• Author: The user who made the change.
• Status: The type of change made to the item (edited, imported, new, and deleted).
• Area: The type of item (catalog, design, marketing, media, pricing, and setting).
• Application: The type of storefront application a design item belongs to (Storefront
Classic or Open Storefront Framework).
Click Clear Filters to clear all check boxes and display all the items that were filtered
out by the Filter By options.
To use the Filter Change List field, begin typing in the field. The list changes to
include those items matching your criteria.
To sort the displayed items from newest or oldest, click the Sort dropdown at the top of
the page and select a sort order.

Schedule publishing
You can publish the active workset immediately or schedule a future date and time to
publish it.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You can also schedule a full publish, which publishes all worksets at once.

Publish a workset
You can publish the active workset immediately or schedule it to publish at a future
time.
To schedule a publish:
1. Navigate to the Changes page of the workset you want to publish from the Active
Workset dropdown list.
2. Click the Publish Workset button.
Commerce displays the workset's Review and Schedule page.
If the workset contains any dependencies, they are listed on this page. See
3. Specify when to publish the workset:
To publish the workset right now, click Publish Immediately.
To publish the workset at a future time, click the Start Time field to display a
calendar/clock widget where you can pick a future date and time. (Click Done to
close the widget.) Then click Publish at Selected Time.

25-6
 Chapter 25
Publish changes using the REST API

If another publish has already been scheduled for the date and time you choose, Commerce
displays an error and you cannot schedule the event until you pick a date and time that does
not conflict with another scheduled publish. You can reschedule a workset publish by
following these steps and publishing immediately or selecting a different time to publish.

Schedule a full publish

A full publish targets all changes in all worksets. When a full publish runs, all unpublished
worksets, even those that are not currently scheduled to publish, are published to your
production storefront. When the full publish finishes, all worksets (except the #default
workset) are removed from the schedule and deleted.
You can schedule a full publish to run one time, or you can create a schedule that runs full
publishes at regular intervals, for example, nightly.
To schedule a full publish:
1. On the Publishing Schedule page, click Add to Schedule and select Full Publish...
from the dropdown list.
2. In the Schedule Full Publish dialog, enter the following information:
• A name for the publish event. The name is optional. If you do not enter a name,
Commerce uses the default name, Unnamed publishing event.
• If you are scheduling a one-time full publish event, set a start date and time, and
ensure the Repeat field is set to None. The Stop Time field is disabled for one-time
publish events.
• If you are scheduling a recurring full publish, set a start date and time, and use the
Repeat menu to select a time period—hourly, daily, weekly, monthly, or yearly.
The dates and times you specify here use the time zone you configured on the
Location tab on your store's Setup settings. For information on viewing and changing
the time zone, see Enter basic store information.
3. Click Schedule.
The new event appears on the Publishing Schedule page.
Once you have scheduled a full publish, you cannot reschedule it. You must cancel it and
then schedule a new one.

Cancel a scheduled publish

You can cancel a scheduled workset publish or a full publish on the Publishing Schedule
page.
• To cancel a full publish, click the event's Delete from Schedule icon.
• To cancel a workset publish, click the workset's Unschedule Workset icon.
Canceling a publish does not delete the workset, but marks it as Not Scheduled in the
Publishing Schedule.

Publish changes using the REST API

In addition to publishing with the administration interface, you can use the Admin API to
manage worksets, publish changes, and get information about recent publishing events.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

25-7
 Chapter 25
Publish changes using the REST API

You can use Admin API endpoints to perform tasks related to worksets and publishing,
including:
• Create and manage worksets
• Specify a workset for a publishable item's changes
• Publish changes
• Download information about recently-published worksets
You can find detailed information about individual endpoints in the REST API
documentation that is available through the Oracle Help Center. Be sure to select the
version of the REST API documentation that matches the version of Oracle Commerce
you are using.

Manage worksets
The Worksets endpoints let you perform basic CRUD operations (create, read, update,
and delete) .on worksets.
• createWorkset creates a new workset with a name you specify.
• deleteWorkset deletes the workset whose ID you specify. A workset must be
empty before you can delete it. You can use the assignPublishingChangeList
endpoint to move changes from one workset to another.
• getWorkset returns the workset whose ID you specify.
• listWorksets returns a list of worksets. You can control the worksets returned in
the response with query parameters.
• updateWorkset updates the name of the workset whose ID you specify.

Specify a workset for an item

When you save a change to a publishable item in the administration interface,
Commerce automatically saves it to the active workset. Endpoints that create or edit
publishable items (for example, updateProduct), however, save changes to the
default workset. To save changes to a different, existing workset, the request must
include the X-CC-Workset header. For example, including the following header saves
changes made by the request to the workset whose ID is ws20001.

"X-CC-Workset": "ws20001"

The assignPublishingChangeList endpoint moves a publishing change list and its

dependencies from one workset to another. For example, the following request moves
a publishing change list from the default workset to a workset whose ID is ws20001:

POST /ccadmin/v1/publishingChangeLists/assignPublishingChangeList

{
"fromWorkset": "default",
"toWorkset": "ws100001",
"changeListId": "ijUCLwsUEiXLLuDjGWmrQriHM_10000"
}

25-8
 Chapter 25
Publish changes using the REST API

You get changeListId and fromWorkset by sending a GET request to /ccadmin/v1/

publishingChanges endpoint. You can control the items returned in the response with query
parameters.
See Understand worksets for more information.

Schedule publishing
You can publish a workset immediately or schedule a future date and time to publish it. Use
the publishChangeLists endpoint to start or schedule a publish.

The following request publishes a workset immediately.

POST /ccadmin/v1/publishingChangeLists/publish

{
"operationType":"selective_publish",
"worksetId" : "default"
}

If the publish successfully starts, the endpoint returns a response similar to this:

{
"publishRunning": true,
"statusMessage": "A publish has been successfully initiated."
}

The following request schedules a worksheet publish for a future time.

POST /ccadmin/v1/publishingChangeLists/publish

{
"operationType":"selective_publish",
"dateTime":"2021-09-03T20:30:00.000Z",
"worksetId" : "default",
"eventName":"My publishing event"
}

If the publish is successfully scheduled, the endpoint returns the repositoryId for the
publishing event.

{
"repositoryId": "300001"
}

The following request schedules a full publish, which publishes all worksets at once. When a
full publish runs, all unpublished worksets, even those that are not currently scheduled to
publish, are published to your production storefront. When the full publish finishes, all
worksets (except the default workset) are removed from the schedule and deleted.

POST /ccadmin/v1/publishingChangeLists/publish

25-9
 Chapter 25
Publish changes using the REST API

{
"operationType":"full_publish",
"dateTime":"2021-09-03T20:30:00.000Z",
"eventName":"Full event"
}

See Schedule publishing for details about publishing.

Download information about recently published worksets

You can get information about publishing events that successfully completed during
the last seven days with the Publishing History endpoints. The information returned by
these endpoints helps you easily understand what items were published recently and
provide an audit trail of what was changed on the storefront over the past week.
The Admin API includes the following Publishing History endpoints:
• GET /ccadmin/v1/publishingHistory returns an array of publishes from the last
seven days. Each array includes high-level information about each publishing
event in the array.
• GET /ccadmin/v1/publishingHistory/{id} provides the same information as /
ccadmin/v1/publishingHistory, but for a specific publishing event.
• GET /ccadmin/v1/publishingHistory/{id}/changes provides detailed
information about a specific publishing event.
Keep the following points in mind about how the Publishing History endpoints work:
• The endpoints return information about publishing events that completed
successfully. No information about failed publishing events is returned.
• The endpoints do not return any information about changes made by direct catalog
editing or direct price editing. For more information about these features, see Edit
catalog items without publishing and Update prices without publishing.
• The endpoint responses include same list of items that appear in a publishing
change list. Secondary items, such as translations, are not returned in the
responses.
• Certain changes you make to the catalog, such as creating a new product type or
changing a price list group, appear as a single item called Catalog Configuration.
Endpoint responses include these changes as individual items.
GET /ccadmin/v1/publishingHistory returns an array of publishes from the last
seven days. For each publishing event returned, the response includes the name and
profile type of the user who started the publish, the type of publish
(selective_publish when a workset is published or publish when all worksets are
published at once), the name and ID of the publishing event, the start and end date
and time, the number of high-level items published, the name of the workset published
(for a full publish, this value is null), and the names of users who made changes that
were published.
GET /ccadmin/v1/publishingHistory/{id} returns information about a specific
publishing event. The response includes the same information as the /ccadmin/v1/
publishingHistory response, but for the specified event only. The sample request

25-10
 Chapter 25
Publish changes using the REST API

GET /ccadmin/v1/publishingHistory/publish3002 returns details like the following in the

response:

{
"publishInitiator": "admin:User,Admin",
"worksetName": "default",
"eventName": "default",
"numberOfHistoricalChanges": 1,
"startTime": "2022-03-03T19:02:35.000Z",
"operationType": "selective_publish",
"id": "publish30002",
"endTime": "2022-03-03T19:02:45.356Z",
"publishInitiatorProfileType": "adminUI",
"authors": [
"admin:User,Admin"
],
"worksetId": "default"
}

GET /ccadmin/v1/publishingHistory/{id}/changes returns an array of items published in a

specific publishing event. For each published item returned, the response includes the ID of
the publishing event, the display name and ID of the item, the name, ID, and profile type of
the last author who changed the item, the date and time of the last change, the type of
change (0 = update, 1 =delete, or 2 = create), the type of item changed (for example,
product), an array of change details, with change time and author information for each
change, and an array of the authors who changed the item.
The sample request GET /ccadmin/v1/publishingHistory/publish3002/changes returns
details like the following in the response:

"items":[
{
"lastName":"User",
"authorProfileType":"adminUI",
"displayName":"The Girl with the Dragon Tattoo",
"author":"admin",
"changeType":0,
"subsystem":"OCCS-Admin",
"assetType":"product",
"changeDetails":[
{
"changeTime":"2022-03-03T19:01:32.000Z",
"author":"admin"
},
{
"changeTime":"2022-03-03T19:01:39.000Z",
"author":"admin"
},
{
"changeTime":"2022-03-03T19:01:44.000Z",
"author":"admin"
}
],
"changeTime":"2022-03-03T19:01:44.000Z",

25-11
 Chapter 25
Publish changes using the REST API

"assetTypeDisplayName":"Product: Base Product",

"firstName":"Admin",
"assetId":"Product_36Exy",
"id":"change30004",
"authors":[
"admin:User,Admin"
]
}
]
}

Use query parameters with Publishing History endpoints

The Commerce REST APIs support a number of query parameters that you can use to
control what data is returned in GET endpoint responses. You can use query
parameters to filter the publishing data returned in the endpoint responses or to page
through the results. These can be useful when you publish frequently or have
publishes that include a large number of changes.
This section includes sample requests that show query parameters that you might find
useful for the Publishing History endpoints. For complete details about how to use
query parameters with the REST APIs, see REST API query parameters.
Depending on how often and how many changes you publish, the Publishing History
responses can be quite large. To prevent the response from becoming too large, the
number of items returned is limited by default to 250. You can override this value by
using the limit query parameter to specify a different number. For example, the
following call limits the number of publishes returned to 5.:

GET /ccadmin/v1/publishingHistory?limit=5

To page through the results, you can use the offset parameter. For example, suppose
you have returned the first group of 250 publishes using this call:

GET /ccadmin/v1/publishingHistory

You can return the next group of 250 using the following call:

GET /ccadmin/v1/publishingHistory?offset=250

The default value of offset is 0, which means the listing begins with the first item. So
setting offset to 250 means the listing begins with the 251st item. You can use limit and
offset together. For example, to return the 401st through 600th publish:

GET /ccadmin/v1/publishingHistory?limit=200&offset=400

You can use the fields parameter to return only certain properties you explicitly
specify. The following sample request returns an array of only the publish IDs and
published workset names of the publishing events.

GET /ccadmin/v1/publishingHistory?fields=[Link],[Link]

25-12
 Chapter 25
Publish changes using the REST API

You can use the exclude parameter to exclude certain properties from the response. For
example, suppose you don't need to know anything about the authors for a publishing event.
The following sample request excludes that information from the response:

GET /ccadmin/v1/publishingHistory/publish3002?exclude=[Link]

The following sample request returns an array that include changes made by the author
Merchandising User.

GET /ccadmin/v1/publishingHistory?q=authors eq "User,Merchandising"

25-13
26
Configure Business Accounts
Oracle Commerce allows you to create accounts for companies that do business with you,
such as manufacturers, distributors, and wholesalers.
Each account represents a single organization and a unique customer. Only Commerce
users whose accounts include the Administrator role can set up accounts for organizations,
and work with these accounts using the administration interface. See Understand Role-based
Access Control for more information.
Note: This feature may not be enabled in your environment.
With Oracle Commerce, you can also allow a prospective account-based shopper to submit a
new account registration request for an account using the store. This feature lets a shopper
submit a new account registration request by providing required business details. After
submitting the required details, the information is reviewed by an administrator from the
merchant side and, if needed, there may a request for additional details such as credit checks
and more. The request is then either approved or rejected. If the request is approved, the
new contact for the account is activated.

Understand accounts, contacts, and contracts

Account-based commerce uses a combination of accounts, contacts, and contracts to
manage access to a storefront by companies that do business with you.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

In order to provide an organization with access to an account-based storefront, the

organization needs an account on that storefront with pertinent details such as the
organization name, logo, billing and shipping addresses, tax reference number, and so on.
An account can contain sub accounts that represent multiple hierarchies of organizational
structure. For example, a principal account represents a company. That account can contain
a number of sub accounts that represent divisions or business units, and each division sub
account can contain a sub account for each department in the division. Sub accounts can
automatically inherit account properties, billing and shipping addresses, and contract details
from parent accounts. See Work with accounts for more information about creating accounts.
See Configure page layouts for account hierarchies for information about how to configure
layouts and widgets to support hierarchies.
Each account is associated with a list of contacts. A contact is an individual within an
organization who is allowed to purchase from the account-based storefront. You create
contacts in the Commerce administration interface, but you can also assign delegated
administration privileges to contacts so they can create and manage other contacts. See
Understand delegated administration and Work with account contacts for more information.

Work with Multiple Stores from One Commerce Instance

When working with multiple sites, accounts must be associated with a contract, which
assigns a catalog and a group of price lists for a given site. A contract between the storefront

26-1
 Chapter 26
Understand delegated administration

and the organization defines what products the organization can purchase on the site
and how much it will pay for them. Note that before a contact can access a site, the
contact’s account must have an associated contract.
You can configure the following business account-specific information on a per site
bases:
• contracts
• approval settings
• payment method types
• shipping methods
For additional information on working with multiple sites, refer to the Run Multiple
Stores from One Commerce Instance.
If a primary account includes sub accounts, each sub account automatically inherits its
parent’s contracts by default. See Work with account contracts for more information.

Understand delegated administration

Once you set up an account for an organization, you can assign roles to contacts that
allow them to manage certain aspects of their accounts.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Delegated administrators do not have access to the Commerce administration UI.

Delegated administrators perform all account-management tasks on their My Account
pages, which are available once they log into your store.
Changes saved by a delegated administrator or approver are immediately visible both
on the storefront and in the Commerce administration interface.
See Understand account-based roles for details on the roles available to contacts.

Work with accounts

Commerce administrators use the administration interface to work with accounts.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Administrators can create and modify accounts, as well as provide account

information, such as addresses, contacts, contracts and logos. Accounts can access
multiple sites. Once you have created an account, you can use the site selector to
choose the site to work with. Once you have created account assets, such as a
contact or a contract, you can indicate which sites to work with using the All Sites tab.
For a user to successfully log into a store, the account must be active, the user’s
contact should be active and the account should be associated with a valid contract. If
a business has multiple entities, such as departments or divisions, that require a
different set of products or prices, you can create a separate sub account for each
entity.
Each contact can be associated with multiple principal accounts and sub accounts,
though in the case where a contact is associated with more than one account, you can

26-2
 Chapter 26
Work with accounts

assign a default account to each contact. When a contact that is associated with more than
one account is logged into your online store, they can switch to any of their active accounts
by selecting an account from a drop-down list in the store’s header. They can add items to the
cart for one account, then switch to another account and add items to that account’s cart. The
shopping cart for one account persists while a contact is shopping for another account.
Contacts must be created by either a Commerce administrator or another contact who is a
designated administrator. Contacts cannot register on your store themselves.

Create an account
You can specify whether a new account is a principal account or a sub account:
• A principal account is an account that does not have a parent account. It can be a stand-
alone account or it can be the top-level account in an account hierarchy.
• A sub account is the child account of another account in an account hierarchy.
When you create sub accounts, Commerce does not limit the depth of the hierarchy, but
sub accounts inherit account properties only up to the 14th level.
To create a new principal account:
1. On the Accounts List page, click New Account.
2. Enter the information that identifies the new account. See the table that follows this
procedure for information about each property.
By default, Principal Account is already selected under Location in Hierarchy.
3. Click Save.
4. Now you can associate addresses, contacts, and contracts with the account you just
created. See Work with account addresses, Work with account contacts, and Work with
account contracts for more information. You can also work with an account’s order
approval settings. See Use Order Approvals for more information.
To create a new sub account:
1. On the Accounts List page, click New Account.
2. Enter a name for the account in the Account Name box.
3. Under Location Hierarchy, select Sub Account.
4. Click the Edit button next to the Parent Account box.
5. Select an account from the list. You can filter the list by typing or pasting some text in the
Accounts box.
The filter control matches letters or numbers that you type, wherever they appear in the
name or ID, not just at the beginning. Usually, as you type more characters, there are
fewer matches. When you see the account you want, select it.
6. Click Done.
7. By default, the sub account inherits its Description, Classification, DUNS Number,
Account Type, Unique Identification Number, Tax Reference Number, VAT Reference
Number, and Account Logo from the parent account. To replace an inherited value,
uncheck the Inherit checkbox next to the property you want to change, and then enter the
new information. See the table that follows this procedure for information about each
property.
8. Click Save.
9. Now you can associate addresses, contacts, and contracts with the account you just
created. See Work with account addresses, Work with account contacts, and Work with

26-3
 Chapter 26
Work with accounts

account contracts for more information. You can also work with an account’s order
approval settings. See Use Order Approvals for more information.
The following table describes the properties that identify an account.

Property Description
Account Logo The logo to be associated with this account.
See
#GUID-51A1A670-5581-42A3-8827-58FA3D9
7DF07/TITLE_X5J_43Z_HHB for more
information.
Account Name The name of the account. This field is
required.
Account Type The account type can be none, company,
division, department or group. Default is set to
none.
Active Activates the new account. If an account is not
active, none of the contacts associated with it
will be able to log into the store.
Classification Identifies the type of account: Standard,
Preferred and Enterprise, OEM, Distributor
and Supplier
Description A description of the account.
DUNS Number If used, a DUNS number is a unique nine-digit
number employed by businesses who have
established Dun & Bradstreet credit.
Location in Hierarchy Indicates if this is a principal account or it is a
sub-account.
Tax Reference Number If used, a tax reference number associated
with the account.
Unique Identification Number If used, the account’s Unique Identification
Number.
VAT Reference Number If used, the account’s Value Added Tax
identification number.
Additional Information If custom properties were created for
accounts, they appear at the bottom of each
account’s General tab, in the Additional
Information section.
Custom account properties are created with
the Commerce Admin API. Once a custom
account property is created, the property is
added to all accounts, including accounts that
already existed when the custom property was
created.
For more information, see Create custom
properties for accounts.

Find accounts
You can search for an account by entering any part of the account name into the
search field at the top of the Accounts List page.
You can search by multiple criteria, including custom properties, by following these
steps:

26-4
 Chapter 26
Work with accounts

1. Click the advanced search icon to the right of the search field to display the Advanced
Search dialog.
2. Select a property from the drop-down list.
You can search by account name, account ID, or any custom short text properties that
have been added to the account.
3. Click Add Criteria to add another property to the search.
Each search can contain up to five properties.
4. If you are searching on more than one property, select one of the following:
• Match all: (default) Search results include the accounts that match all the search
criteria. If an account matches some of the criteria but not all, it is not returned.
• Match any: Search results include the accounts that match any search criteria.
5. Click Search.

Associate a contact with an account

You can create contacts without associating them with an account by following the
instructions described in Work with account contacts. This section describes how to associate
existing contacts with an account.
Note: A sub account does not inherit its parent account’s contacts. You must add manually
add contacts to a new sub account.
To associate a contact with an account:
1. On the Accounts page, click Accounts List and select the account to modify.
2. Click the Contacts tab.
From this screen you can create a new contact or associate an existing contact. When you
add a contact to an account, Commerce sends an email to the contact’s address that
contains a link for setting a new password. The password must conform to the password
policy you set on the Shopper Settings page. For more information, see Configure Shopper
Settings.
To create a new contact to associate with an account:
1. Select the New Contact button.
2. Enter the required fields, which include Last and First Name, and Email/Login ID.
Note: You cannot modify the email address once the contact has been saved.
3. Verify that the account displayed is the correct account.
4. Click the Active check box to activate the contact.
Note: Only active contacts can log into the store.
5. Click Save.
To associate an existing contact:
1. Select Add Contact button.
2. Select the contact from the table
3. You can search for a contact by entering the first name, last name or email address into
the search field.
4. Click Add.

26-5
 Chapter 26
Work with accounts

Modify an account
Only an Oracle Commerce administrator can modify an account using the following
steps:
1. On the Accounts page, click Accounts List and select the account to modify.
2. If you have multiple sites, use the All Sites tab to select the site associated with
the account.
3. Enter the updated information for the account.
4. Click Save.

Add account approval

You can add account approval limits to an account. Note that approval limits are site
specific. Refer to the Use Order Approvals section for information on order approvals.
Set the approval limits using the following steps:
1. On the Accounts page, click Accounts List and select the account to modify.
2. Select the Approvals tab.
3. Check the Require approval checkbox and set the approval limit.
4. If your environment uses an external service that can determine approval settings,
select the check box. See Use Webhooks for information on extending the Order
Approval services and working with webhook APIs.

Add or change an account logo

Logos or media files must be loaded using the Media page before they can be
associated with an account. Refer to the Upload media files section for information.
To add or change a logo, perform the following steps:
1. On the Accounts page, click Accounts List and select the account to modify.
2. Click the Select Image button.
3. Select the media file from the Media Library.
4. Click Add.
5. The image is displayed in the logo field.
You can delete the logo by clicking the X in the upper right corner.

Move an account
You can move an account to a new position in its current hierarchy or you can move it
to a different hierarchy. Keep the following in mind when you plan to move an account:
• You cannot make a parent account a sub account of any of its children. For
example, you cannot make a principal account a sub account in its current
hierarchy.
• You can move both principal and sub accounts to different hierarchies.
• Changing a sub account to a principal account moves it to the top of a new
hierarchy.
• When you move a parent account, all its sub accounts move with it.

26-6
 Chapter 26
Work with accounts

• Any account keeps its addresses, contracts, and contacts when you move it. If an
account has no addresses and you move it to be a sub account, it automatically inherits
any available addresses from its new parent.
To make a sub account a principal account:
1. On the Accounts page, click Accounts List and select the account to move.
2. Click Principal Account under Location in Hierarchy.
3. If the account inherited property values from its parent, you must replace those values.
See #GUID-51A1A670-5581-42A3-8827-58FA3D97DF07/GUID-E3CA4A72-
A9F7-4247-9BED-57F8F4BA88FA for details about account properties.
To move an account to a new parent:
1. On the Accounts page, click Accounts List and select the account to move.
2. If the account is currently a principal account, click Sub Account under Location in
Hierarchy.
3. Click the Edit button next to the Parent Account box.
4. Select an account from the list. You can filter the list by typing or pasting some text in the
Accounts box.
The filter control matches letters or numbers that you type, wherever they appear in the
name or ID, not just at the beginning. Usually, as you type more characters, there are
fewer matches. When you see the account you want, select it.
5. Click Done.
6. By default, the moved account inherits its Description, Classification, DUNS Number,
Account Type, Unique Identification Number, Tax Reference Number, VAT Reference
Number, and Account Logo from the parent account. To replace an inherited value,
uncheck the Inherit checkbox next to the property you want to change, and then enter the
new information. See the table that follows this procedure for information about each
property.
7. Click Save.

Deactivate an account
You cannot delete an account; however you can deactivate an account. When an account
has been deactivated, no contact that has been associated with the account will be allowed
to log into the store.
1. On the Accounts page, click Accounts List and select the account to deactivate.
2. Uncheck the Active checkbox to indicate that the account has been deactivated.
3. Click Save.

Associate shipping and payment methods with an account

When you create or update an account, you can specify shipping and payment methods used
with the account. These methods can be set for accounts that are associated with a site.
Before you can associate any shipping or payment methods, you must configure the methods
so that shoppers can use them. Shipping methods, which are configured using the Settings >
Shipping Methods tab, are described in the Configure Shipping. Payment methods are
selected using the payment gateway tab in Settings > Payment Gateways. For information on
configuring payment methods, refer to the Configure Payment Processing.

26-7
 Chapter 26
Work with account addresses

To associate shipping and payment methods:

1. Select or create an account.
2. Select the Shipping/Payment tab.
3. If you click the Use All of the Site Shipping Methods checkbox, all of the
shipping methods used on the currently selected site will be available and will be
displayed.
If you deselect the check box, add the shipping methods to use. You can select
multiple methods
4. If you click the Use All of the Site Payment Method Types checkbox, all of the
payment method types used on the currently selected site will be available. If you
deselect the check box, add the payment method types to use. You can select
multiple methods.
Note that if the shipping method or payment method type is added to a site in Settings,
and you have not selected the associated Use all check box, you must manually add
the new shipping or payment method to an account before shoppers can use it.
A shipping method or payment method type that is associated with an account/site pair
cannot be removed or disabled. You can remove the association by going to the
account’s Shipping/Payment table, selecting the site and deleting the shipping or
payment method.

Work with account addresses

Each account can be associated with multiple addresses, such as billing and shipping
addresses in different states.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

An account’s addresses appear in the following places:

• The Managed Account Address Book is seen by each of the account’s logged-in
contacts. Contacts who are buyers can select billing and shipping addresses from
the available account addresses when they place orders. Additionally, contacts
who are delegated administrators and/or Account Address Managers can add and
manage addresses for the account from their My Account page on the storefront.
• The Address pane in the Commerce administration interface. Only Commerce
administrators can see and work with addresses here. Contacts who are
delegated administrators cannot access the Commerce administration interface.

Create account addresses

To create an address for an account:
1. Navigate to the account’s Addresses page in the administration interface or on the
storefront:
• Commerce administrators in the administration interface: On the Accounts
page, click the name of the account. Then click the Addresses button on the
left-hand side of the screen.
• Delegated administrators on the storefront: Click My Account, then click
Account Addresses.
2. Click New Address and enter the address details.

26-8
 Chapter 26
Work with account addresses

The table that follows this procedure describes the Address properties. Address
properties in this table are part of the default address format that ships with Commerce. If
your Commerce environment includes custom address formats, different properties might
be available when you create an address. Additionally, custom address formats might
make some of the required properties in this table optional. Contact your Site
Administrator for details about creating addresses with custom address formats.
3. Click Save.

Property Description
Nickname (Required) An internal name that identifies the
address in both the administration console and
contacts’ account address book.
Nicknames do not have to be unique across
addresses or accounts.
Company Name (Required) The name of the company.
Phone Number (Required) A phone number for the company.
Address Line 1 (Required) First line of the address. For example,
1000 Smith Street.
Address Line 2 Second line of the address. For example, 4th
Floor.
City (Required) Name of the city where the address is
located.
Province/State (Required) Province or State where the address is
located.
Country (Required) The country where the address is
located.
Postal/ZIP Code (Required) Postal/ZIP code for the address.
Type Commerce includes two types of addresses by
default: Billing and Shipping. Your environment
might also contain custom address types that you
can select from the Type list. You can assign more
than one type to each address.
Default Shipping Address When a contact checks out on your store, the
default shipping address is automatically selected
and appears at the top of the list of available
shipping addresses.
Only one account address can be the default
shipping address.
By default, a sub account inherits its parent’s
default shipping address. Changing the default
shipping address for a sub account does not
change it for the parent.
Default Billing Address When a contact checks out on your store, the
default billing address is automatically selected
and appears at the top of the list of available billing
addresses.
Only one address can be the default billing
address.
By default, a sub account inherits its parent’s
default billing address. Changing the default billing
address for a sub account does not change it for
the parent.

26-9
 Chapter 26
Work with account contacts

Edit or delete account addresses

To edit or delete an address:
1. Navigate to the account’s Addresses page in the administration console or on the
storefront:
• Commerce administrators in the administration interface: On the Accounts
page, click the name of the account. Then click the Addresses button on the
left-hand side of the screen.
• Delegated administrators or Account Address Managers on the storefront:
Click My Account, then click Account Addresses.
2. Select the name of the account with the address to modify.
3. Make the edits to the address.
4. Once you have made your changes, click Save.
5. To delete the address, click the delete icon in the upper right corner of the
address.

Work with account contacts

Contacts are shoppers who perform various activities for the account.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Each contact can be associated with multiple principal accounts and sub accounts,
though in the case where a contact is associated with more than one account, you can
assign a default account to each contact.
When working with multiple sites in a single Commerce instance, before a contact can
access a site, the contact’s account must have an associated contract.
Contacts must be created by either a Commerce administrator or another contact who
is a designated administrator. Contacts cannot register on your store themselves.
The list of an account’s contacts appears in the following places:
• The My Account page seen by the account’s delegated administrators. Delegated
administrators can add and manage accounts for the account from their My
Account page on the storefront.
• The Contacts pane in the Commerce administration interface. Only Commerce
administrators can see and work with contacts here. Delegated administrators
cannot access the Commerce administration interface.

Understand account-based roles

Roles grant access permissions to account-based contacts. These roles allow you to
specify the actions that each contact can perform. Note that a contact can have more
than one assigned role.
Commerce defines two types of storefront roles:
1. Standard roles - These roles are defined for use across all existing and new
accounts. These can be assigned to B2C as well as B2B users. These roles can
be assigned to a user either globally or in the scope of one or more accounts.

26-10
 Chapter 26
Work with account contacts

Note:
In earlier versions of the storefront access control system, standard roles were
referred to as global roles.

2. Account roles – Also called organizational roles, applies to a single account only. If a
contact is assigned an account role, the role grants access to functions only in the
account in which the role is defined.
Merchants can create custom roles – both standard and account, and even allow other B2B
storefront users to create custom roles for their account needs.
For details on creating and managing Storefront roles, see Understand access control for
account-based storefronts.
We provide the following pre-defined account roles that you can assign to a contact:

Role Description
Account Address Manager Contacts that have the right to create, edit and
delete account addresses. Additionally, these
contacts have the ability to manage account
addresses during the checkout process.
Administrator Assigning this role lets you delegate some
administrative tasks to a contact. Delegated
administrators can create, and manage contacts
for their accounts, including assigning and
removing administrator and approver privileges for
other contacts. They can also view, create, and
manage addresses for their accounts, including
specifying a default billing and shipping address
for an account. Delegated administrators can only
see and work with contacts and addresses for
accounts to which they are assigned.
Approver Assigning this role lets you delegate the task of
approving orders to a contact. Approvers can view
and approve any orders in their accounts that
require approval, including their own orders.
Approvers can only see and work with orders for
accounts to which they are assigned. For further
information, refer to the Use Order Approvals
section.
Buyer The default role, which allows the contact to
purchase items from the account-based catalog.
Profile Address Manager Contacts that can create, edit and delete profile
addresses. Additionally, these contacts have the
ability to manage profile addresses during the
checkout process.

To assign roles to a contact:

1. Create a new contact, or select a contact to work with.
2. Select Accounts Membership.
3. Click the edit icon.
4. Select the Account Address Manager or Profile Address Manager Storefront Roles
and click Save.

26-11
 Chapter 26
Work with account contacts

For roles for internal users, see Configure Internal User Accounts.

Create a contact
Both Commerce administrators and contacts who are delegated administrators can
create new contacts. Commerce administrators can create contacts for all accounts,
as well as contacts that are not associated with any accounts. Delegated
administrators can create new contacts only for their own accounts.
The process of creating a contact does not include assigning a password. When a
contact is associated with an account, Commerce automatically sends an email to the
contact that contains a link for setting a new password. The new password must
conform to the password policy you set on the Shopper Settings page. For more
information, see Configure Shopper Settings.
In order for a contact to receive the email they use to create their password, your store
must have an email service configured and you must customize and enable the
Account Assignment Changed email template. For more information, see Configure
Email Settings.
To create a contact as part of an account:
1. Navigate to the account’s Contacts page in the administration interface or on the
storefront:
• Commerce administrators in the administration interface: On the Accounts
page, click the name of the account. Then click the Contacts button on the
left-hand side of the screen.
• Delegated administrators on the storefront: Click My Account, then click
Contacts.
2. Click New Contact and enter the contact’s details.
3. Click Save.
4. Click the Account Memberships link.
5. Select the storefront roles for this contact.
6. Save your changes.

Edit a contact
You can edit a contact’s first name, last name, account, active status, and the values
of any custom properties. You cannot edit the email address or password. Contacts
who forget their passwords must click the Forgotten Password link on the store’s login
page and enter their login email address. Commerce sends a link to the email
address. The contact clicks the link to reset their password. If the link has expired
when the contact clicks it, they see a page where they can request a new link.
To edit a contact do the following:
1. Click the Settings icon, then click Accounts.
2. Click the New Contact button.
3. Enter the information for the new contact. See the two tables that follow this
procedure for information about each field.
4. Once you have made your changes, click Save.
Refer to the Configure the password policy for information on resetting contact
passwords.

26-12
 Chapter 26
Work with account contacts

The following table describes the contact’s General properties.

Property Description
Last Name The last name of the contact. This field is required.
First Name The first name of the contact. This field is
required.
Email Address/Login ID The email address of the contact. The contact
uses this email address to log into your store. This
is also the address where Commerce sends email
that the contact uses to set their password. This
field is required.
Note: Once the contact has been created, you
cannot modify the Email Address/Login ID.
Active Specifies whether the contact is active. Only active
contacts can log into the store, see catalogs and
prices associated with their accounts. Active
contacts are active on all accounts they are
associated with.
Additional Information If custom properties were created for shopper
profiles, they appear at the bottom of each
contact’s General tab, in the Additional Information
section.
Custom profile properties are created with the
Commerce Admin API. Once a custom profile
property is created, the property is added to all
shopper profiles, including any profiles that
already existed before the custom property was
created. For more information, see Add custom
properties to a shopper type.
Custom profile properties do not automatically
appear on your store, for example, when a
delegated administrator creates a new contact. To
allow custom profile properties to be displayed and
edited on your store, you must write custom
widgets to retrieve the values of custom profile
properties, and also set the values of any custom
properties you have created. See Access custom
properties using the UserViewModel for more
information.

The following table describes the contact’s Account Memberships properties.

Property Description
Default Account The account that this contact is automatically
associated with when they log into your store.
Each contact can be associated with only one
default account.
Only Commerce administrators see this property.
Delegated administrators cannot assign a new
contact to a different default account.
Accounts All accounts with which this account is associated.
Only Commerce administrators see this property.
Delegated administrators cannot assign a new
contact to accounts.

26-13
 Chapter 26
Work with account contacts

Property Description
Storefront Roles Specifies the contact’s role for an account. You
can assign different roles to a contact for each
account they are associated with.
Commerce administrators can assign roles to all
contacts. Delegated administrators can assign
storefront roles only to contacts in accounts for
which they have the Administrator role.
Refer to the Understand account-based roles for
detailed information on each role.

Find contacts
You can search for a contact by entering first name, last name, or email address into
the search field at the top of the Contacts List page.
To search by multiple criteria, including custom properties, click the advanced search
icon to the right of the search field to display the Advanced Search.
1. Select a property from the drop-down list.
You can search by first name, last name, email address or any custom short text
properties that have been added to profiles.
2. Click Add Criteria to add another property to the search.
Each search can contain up to five properties.
3. If you are searching on more than one property, select one of the following:
• Match all: (default) Search results include the contacts that match all the
search criteria. If a contact matches some of the criteria but not all, it is not
returned.
• Match any: Search results include the contacts that match any search criteria.
4. Click Search.

Deactivate a contact
You cannot delete a contact, but both Commerce administrators and delegated
administrators can deactivate a contact. Contacts who are no longer active cannot log
into any of the accounts to which they were assigned. See #GUID-7293FC33-
A16B-4C40-A4F3-150198E9F236/TITLE_MRM_MBF_3HB for details about setting a
contact’s Active property.
Commerce administrators can also remove a contact’s association with an account in
the administration interface. See #unique_230/
unique_230_Connect_42_TITLE_DY4_MCZ_HHB for more information.

Allow contacts to create addresses

Business account contacts can be allowed to add or manage an account address or
an individual shopper’s address during the checkout process if they have been
configured with the appropriate role.
This section describes how to work with Storefront Classic widgets. For details about
corresponding OSF widgets, see Design Account-Based Storefront Pages.

26-14
 Chapter 26
Work with account contracts

To allow a contact to create a shopper’s address when placing an order, assign that contact
the Profile Address Manager Role. This role allows a contact to see, select and create a new
profile address when they are working with profiles or placing an order. Note that this role is
not required to see or select a profile when working with profiles or placing an order.)
A contact can also be allowed to create or edit an account address when working with a
profile or placing an order. To do this, give the contact the Account Address Manager role.
Note that this role is not required to see or select an account address when working within
the profile or placing an order. It is possible for a contact to have both the Account Address
Manager and Profile Address Manager roles. By default, the delegated administrator has
both of these roles. Contacts do not have these roles by default.
When implementing this feature on the store front, you need to ensure that you have the
latest version of the Managed Account Address widget, which allows contacts to manage
addresses when placing an order, if they have been assigned the appropriate role. For
information on the Managed Account Address Book widget, refer to the Appendix: Layout
Widgets and Elements.
Additionally, you must create a vertical tab on an instance of the profile layout and ensure that
you have the latest version of Account Address Book widget, which allows the contact to
manage addresses in the Profile area, if they have been assigned the appropriate role. For
information on creating a vertical tab, refer to the Add vertical tabs section. For information on
the Account Address Book widget, refer to the Appendix: Layout Widgets and Elements.

Work with account contracts

Contracts let you associate a particular catalog, price group, and other terms with each
account.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Contracts can be created within the context of a published site. You can associate an account
with more than one contract. This allows you to run multiple sites from a single Commerce
instance. Note that a contact cannot access a site until a contract has been associated with
the contact’s account. For information on working with multiple sites, refer to Run Multiple
Stores from One Commerce Instance.
Once you have defined a contract for an account by associating the account with a catalog
and a price group, you can change the catalog or price group but you cannot leave either
field blank. To prevent a contract from being used, deactivate the account so that all
transactions with the account stop. See Deactivate an account for more information.
If you enable Account Activated or New Contract Added emails, all contacts associated with
an account are notified when a contract is added, or if the account is moved to a new parent,
where it inherits the parent’s contracts by default. See Enable the types of email your store
sends for more information.
Commerce administrators create and manage contracts in the Commerce administration
interface. Delegated administrators cannot perform these tasks.

Create or update an account contract

To create a new contract or update an existing contract:
1. On the Accounts page, select the account whose contract you want to manage.
2. Click the Contract tab to see contract information for the site selected in the site selector.

26-15
 Chapter 26
Understand shoppers and new account registration requests

3. If you are working with a sub account, it inherits its parent account’s contract for
the selected site by default. To replace an inherited contract, uncheck the Inherit
Contact checkbox.
4. Enter or modify the information for the contract. See the table that follows this
procedure for information about each field.
5. Click Save.

Property Description
Catalog (required) A catalog associated with this contract. Only
published catalogs appear in the list of
catalogs you can select from. See Manage
Your Catalog for more information.
Contract Description A description of the contract.
Contract Name (required) The name of the contract.
External Contract Reference Alphanumeric value that allows you to store
contract references from an external system.
Price List Group (required) A price group associated with this contract.
Only active, published price groups appear in
the list of price groups you can select from.
See Configure Price Groups for information.
Site Information on the site associated with this
contract including the site name and URL.
Note that only a published site can be
associated with a contract.
Terms and Conditions Text field to provide terms and conditions of
the contract.

Understand shoppers and new account registration requests

You can allow a prospective account-based shopper to request registration of a new
store account.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Enabling this feature lets a shopper submit an account registration request for a new
account by providing required business details. The information is reviewed by an
administrator from the merchant side after the shopper submits the required details,
and, if needed, the administrator may request additional details from the shopper such
as credit checks. The registration request is then either approved or rejected. If the
request is approved, the new contact for the account is activated.
An example of how the basic process works is provided in the list that follows. This
high-level description is provided only as example and an introduction and does not
necessarily mean that your process would work exactly this way.
For example, all of the emails that are sent during the approval/rejection process are
only lightly touched upon in the example process flow. For more detail on the
automated emails described in the process, refer to Configure Email Settings.
• The administrator for the account-based shopper enables the ability for a shopper
to request registration of a new store account in the Settings area of administrator
user interface. Refer to Configure Account-based Shoppers in the Configure
Shopper Settings section for more details.

26-16
 Chapter 26
Submit new account registration information as a business shopper

• A prospective account-based shopper uses the store user interface to submit a new
account registration request. When the registration request is received, its status at this
point is New.
• The administrator sees the new registration request in the Registration Requests area of
the Accounts page. Refer to Work with account registration requests for more information
on how to view and work with these types of requests.
• The administrator opens the registration request and begins reviewing it.
• The administrator saves some review changes and/or explicitly sets the request status to
Review.
• Another administrator reopens the registration request to review it and decides more
information is needed before an approval decision can be made. This administrator can
then change the status to More Info Needed.
• Outside of the store, the administrator emails the account requester asking for additional
information.
• The account requester sends the administrator the required information and sends it back
to the administrator.
• After reading the account requester’s email, the other administrator opens the registration
request, adds the new/missing information, and sets the registration request’s status
back to Review.
• The original administrator opens the registration request and makes a decision whether
to accept or reject the account request.
• If the administrator accepts the registration request, an approval email is sent to the
account requester. The registration request then disappears from the Registration
Request list and appears in the Account list. The account requester then becomes a
contact in the new account.
• If the administrator rejects the registration request, they can optionally enter comments to
add to the rejection email.
The rejection email is sent to the account requester and the registration request remains in
the Registration Request list with a status of Rejected.

Submit new account registration information as a business

shopper
Prospective account-based shoppers can submit a new account registration request using
the store.

This section applies to Storefront Classic only.

This feature lets a shopper submit a new account registration request for a new account by
providing required business details.
If account-based shoppers is enabled, the shopper who wants to submit a new account
registration request clicks on the Register For An Account link found at the bottom of the
Login dialog box. A form dialog box is presented where they provide their name, address,
phone number, and some notes to accompany their request if needed.
Note: When the API is used to submit a new registration request with multiple addresses,
each address must have a unique nickname. If multiple addresses are submitted with the

26-17
 Chapter 26
Work with account registration requests

same nickname, only one is saved. The same is true when the API is used to create
an account with multiple addresses.
They must also provide a Company Name and Name Of A Related Existing Account (if
needed). Company Name is the name of the company for which the shopper is a
business-to-business buyer. They are not registering as a regular consumer shopper.
The company name will be pre-populated into the Account Name in the General tab
(see below) of the registration request that the administrator sees. The Related
Existing Account field is a piece of information provided by a prospective company
buyer if, for example, they want to be a buyer who wants to register a new account for
the Southern Division of a larger account that already exists. This is where they would
indicate the name of the larger account that already exists. This field is optional.
After this information is entered correctly, the shopper requesting the account clicks
Submit to begin the account request approval process. They receive a Thank You
message that acknowledges that their request has been submitted and that they may
be contacted if more information is needed. The shopper can also click Cancel to
cancel the process.
Once an account request has been submitted, the administrator can go to the
Registration Requests area on the Accounts area and view, update, accept, and reject
account registration requests. Anyone with the administrator and/or account manager
Role can view, update, accept, and reject registration requests.

Work with account registration requests

When the shopper submits the requested initial information, the administrator can see
the new registration request in the Registration Requests area of the Accounts page
where they can then view, search, and work with account registration requests.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Anyone with the Administrator and/or Account Manager Role can view, update, accept,
and reject registration requests.
After the initial submission of the required details by the shopper, the account request
is reviewed from the merchant side by the administrator. At this point, the administrator
may also request from the shopper additional details such as credit checks and more.
Upon receipt of all the requested information, the administrator then either approve or
reject the registration request. If the request is approved, the new contact with the
account is activated and can then begin transacting business.
The new registration request list in the Registration Requests area of the Accounts
page provides the information in a list divided into columns titled Company Name,
Request ID (generated by the system), Request Date, and Status. The registration
request list is paginated.
The Status of a request can be either New (the request is new and has not been
viewed), Review (the request has been viewed or changed and needs to be acted
upon), More Info Needed (the request has been viewed and an action needs to be
taken to collect more account or shopper information before the request is approved or
rejected), or Rejected (the account request has been rejected and no contact has
been activated).
You can use the Commerce Admin REST API to add a custom rich-text property to
accounts that gives administrators a place to log and track internal notes for

26-18
 Chapter 26
Work with account registration requests

registration requests. See Create custom properties for accounts for an example that shows
how to create and use this kind of custom property.
Note: As mentioned, custom properties can be introduced with the registration request once
the request has been approved but they are not saved by default. If you wish to save these
custom properties, you can use the Commerce Admin API to add custom properties to
registration requests by using the updateItemType endpoint with the organizationRequest
item type. For details on doing so, see Use the REST APIs.

Work with the account registration request list

The new registration request list in the Registration Requests area of the Accounts page lets
you do the following:
• Filter the list by status. The default view of the list is to show all statuses.
• Use a typeahead search box. The placeholder text in the box is ‘Filter account requests.”
When you type a string, the list is filtered to records containing that string in the Company
field.
• Sort the list by Request ID, Company, or Request Date. The default sort order is by
Request date.
• Look at other pages of the list as the list is paginated as the list grows longer.

Search for a specific registration request

In the search box found in the Registration Requests list view, you can search for registration
requests by Company or by Request ID.
You can also use an Advanced Search control (same as found in the accounts and contacts
user interfaces) to search for registration requests by creating expressions like the following:

<property 1> contains <value 1>

<property 2> contains <value 2> ...
<property 5> contains <value 5>

You can also specify “Match Any” or “Match All.”

The properties available for this type of search must be:
• Of type string OR
• A custom string property of a registration request, account, or profile OR
• Properties such as Account, Name, Account Number, Company Name, Tax Reference
Number, First Name, Last Name, Email Address, and more.
Also, the Advanced Search control feature presents you with an indented dropdown list of
choices of string properties and custom properties to help you select fields that you may want
to choose from other information groups. Use these steps:
1. Click the advanced search icon to the right of the search field to display the Advanced
Search dialog.
2. Select a property from the drop-down list.
3. You can search by Account, Contact, and Registration Request information groups or
any custom short text properties that have been added to the account.

26-19
 Chapter 26
Work with account registration requests

4. Click Add Criteria to add another property to the search. Each search can contain
up to five properties.
5. If you are searching on more than one property, select one of the following:
• Match all: (default) Search results include the accounts that match all the
search criteria. If an account matches some of the criteria but not all, it is not
returned.
• Match any: Search results include the accounts that match any search
criteria.
6. Click Search.
You can also use a typeahead search box for an account by entering any part of the
account name into the search field at the top of the Registration Requests page.

View and edit account registration list request details

To look at and/or edit an actual new or existing registration request from the list in the
Registration Requests area of the Accounts page, click the Registration ID (which is a
link) of the request found in the list.
Each request displays four tabs of information. Some of the fields on the tabs can be
viewed and some can be edited. These tabs are:
• Request tab containing the following fields:
– Status – A dropdown list that can be used to change the status of the
requests. The choices are New, Accept, Reject, More Info Needed, and
Review.
– Request ID, Registration Request Date, Site Where Request Originated, and
Notes from the requester. These are all Read-only.
• General tab containing the following fields (grayed out if the account was rejected):
– Company Name from Request and Related to Existing Account. These are
Read-only.
– Account Name. This is the Company Name provided by the requester.
– Classification – This is a dropdown list to select details about the classification
of the type of account.
– Account Type - This is a dropdown list to select a specific type of account.
– Tax Reference Number, DUNS Number, Unique Identification Number, and
VAT Reference Number – These are all inherited from the Company Account.
• Contact tab containing the following fields (grayed out if the account was rejected):
– First and Last Name – These are Read-only. For an existing contact, the First
Name and Last Name stored in the system take precedence over those
submitted, and are the ones displayed.
– Email/Login ID – These are editable unless it is the email address of an
existing account-based contact, in which case it is read-only in the UI. (It is
editable via API in either case.). The administrator cannot change the email
address to the email address or login ID of an existing shopper.
• Address tab containing the following fields (grayed out if the account was
rejected). This page displays all addresses that have been submitted. By default,
each address consists of the following editible properties. These address

26-20
 Chapter 26
Work with registration requests to review, change status, approve, and reject requests

properties are part of the default address format that ships with Commerce. If your
Commerce environment includes custom address formats, different properties might be
available on the Address tab. Additionally, custom address formats might make some of
the required properties in this list optional. Contact your Site Administrator for details
about creating addresses with custom address formats.
– Nickname
– Company
– Address 1
– Address 2
– City
– Zip/Postal Code
– Country
– State/Province
– Type
– Phone
If there is no address associated with the request, you are shown the message “This
registration request does not have an associated address.”
Below the tabs, there is a Cancel button and a Save button. If you click Cancel, any changes
you have made are discarded. There is no confirmation dialog. The Save button applies
changes made in all tabs.

Work with registration requests to review, change status,

approve, and reject requests
When you have enabled Account-based Shoppers in the Shopping Settings areas and are
able to view the registration requests, you can see these requests in the Registration
Requests area of the Accounts page.
The following provides an example of the change/approval/rejection process that occurs with
a new registration request.
When a new account request is received, the request enters the system with a status of New
until you either change the status of the request and save it, or you open the request without
changing it.
If you save changes that do not include a status change:
1. An error occurs and the detail view is kept open.
2. If the save is successful and the status is New, the status is then changed to Review. If
there is an exception with provided addresses, then there may have to be some editing
done in another dialog. Finally, close the detail view and return to the list view.
If you save changes that include a status change:
1. If there are changes other than the status change, save them.
2. If an error occurs, you see an error message but the detail view is kept open.
3. If the save is successful, you can move on to making the status change

26-21
 Chapter 26
Work with registration requests to review, change status, approve, and reject requests

If you make a status change of Review or More Info Needed

1. Change the status.
2. Close the detail view and return to the request list view.
If you choose Accept from the status dropdown list while making a status change:
1. You are given the option to provide comments that are added to the acceptance
email sent to the shopper who made the request. The comments are limited to
1000 characters.
2. You are requested to Click Accept to Create this as a New Account. To edit the
account after accepting it, select the account in the Accounts List.
3. If you chose Accept on the confirmation dialog, you are shown a confirmation
dialog while making changes. Be sure to check the uniqueness of the account
name. If it is a duplicate, you receive an error message that the account name
already exists and that you should choose another one. You are also returned to
the list view. Assuming the account name is unique, add the account to the
Accounts UI. The contact is now an active contact on the account.
4. Close the detail view and return to the list view.
5. Remove the registration request from the list view. The account and contact are
both inactive at this point. If the contact is already an active contact, that person
remains active.
6. An approval email is sent to the shopper who submitted the registration request. If
you click Cancel on the confirmation dialog, you are returned to the detail view.
If you chose Reject from the status dropdown:
1. You are given the option to provide comments optional comments that are added
to the rejection email sent to the shopper who made the request. The comments
are limited to 1000 characters.
2. You are requested to Click Reject to Reject the Registration Request. Once this
request is rejected, it can no longer be edited or accepted.
If you click Reject on the confirmation dialog:
1. Change the status to Rejected.
2. Close the detail view and return to the list view.
3. The rejected registration request appears in the list.
4. All fields in the registration request become read-only. In the details view, all of the
tabs besides the Request tab are grayed out.
5. A rejection email is sent to the shopper who submitted the registration request.
6. Clean up the entry after it is rejected. When a registration request is rejected, you
can hard delete the pending contact and organization. Do not delete the contact if
it is an existing contact.
7. The email address (username) of the contact is now free for re-use for a new
account-based or regular (anonymous) contact.

26-22
 Chapter 26
Understand contact registration requests

Understand contact registration requests

In addition to account registration requests, you can allow an existing account-based shopper
(contact) or a registered non-account-based shopper to submit a contact registration request.
A registered non-account-based shopper can be defined as a shopper with an email address
that is not registered. An existing account-based shopper would have an email address that
was registered as part of their role as an account-based shopper.
Note: A logged-in account-based shopper can also submit a contact request with the email
address of a different account-based contact or with an email address that does not exist in
the system. A contact registration request cannot be submitted by/for an existing registered
non-account-based shopper - that is, with the email address of an existing registered non-
account-based shopper. If the email address is that of a registered non-account-based
shopper, the system returns the error message that the email address must be new or be that
of an existing account-based contact.
A contact registration request means that either type of shopper wishes to be added as a
contact to an existing business account. The contact registration request is then either
approved or rejected by a merchant administrator or by a delegated administrator. This type
of request is not the same as an account registration request that is described in previous
sections of this chapter. Unlike account registration requests, there is not an administrator
user interface setting to enable or disable this feature.
The request process feature lets a shopper submit a request to be added as a contact to an
existing business account by providing required contact and account details. The information
is reviewed by an administrator or a delegated administrator from the merchant side after the
shopper submits the required details. If needed, the administrator may request additional
details from the shopper. Additional information that is needed must be requested and
received separately from this feature either via a phone call or through emails. The contact
registration request is then either approved or rejected. If the request is approved, the new
contact for the account is activated and added to the account.

Understand the contact registration request process flow

An example of how this basic contact registration request process works is provided in the
procedural list that follows. Anyone with an Administrator, Delegated Administrator, and/or
Account Manager Role can view, update, accept, and reject contact self-registration requests.
Note: This high-level description is provided only as example and an introduction and does
not necessarily mean that your process would work exactly this way. For example, all of the
emails that are sent during the approval/rejection process are only lightly touched upon in the
example process flow. For more detail on the automated emails described in the process,
refer to Configure Email Settings.
• A registered non-account-based shopper or an existing account-based shopper uses the
store interface (via a widget provided with the layout) to request to be added as a contact
to Account A. Refer to Submit new contact registration information for additional details.
• The registered non-account-based shopper or an existing account-based shopper gets
an email acknowledging that the request has been received. The request’s status is New.
• The administrator or the delegated administrator for Account A are notified via an email
that there is a new contact self-registration request that has been received.

26-23
 Chapter 26
Submit new contact registration information

• The administrator sees the new request in the Contact Registration Requests area
of the Accounts administration user interface. The delegated administrator sees
the request via a widget provided on the store.
• The administrator or the delegated administrator for Account A opens the
registration request and begins reviewing it.
• The administrator or the delegated administrator for the account saves some
changes and/or explicitly sets the status to “Review.”
• The delegated administrator for the account decides more information is needed
before an approval decision can be made and changes the status to “More Info
Needed.”
• Outside of Commerce, the delegated administrator emails the registered non-
account-based shopper asking for information.
• The registered non-account-based shopper sends the delegated administrator an
email with the required information.
• After reading the registered non-account-based shopper’s email, the delegated
administrator opens the request, adds some information, and sets the request’s
status to Review.
• The administrator or the delegated administrator opens the request and makes a
decision.
• If they accept the request then
– Optionally, they provide comments (if needed) to add to the approval email.
– The request disappears from the Request list.
– The registered non-account-based shopper receives an email indicating that
the contact request is approved.
– The shopper now appears as a contact in Account A.
• If the administrator or the delegated administrator rejects the request then
– Optionally, they can provide comments to add to the rejection email.
– The request remains in the Contact Registration Requests list with a status
Rejected.
– The shopper receives an email indicating that their request is rejected.

Submit new contact registration information

Existing account-based shoppers (contacts) or registered non-account-based
shoppers submit a new contact registration request using the store.

This section applies to Storefront Classic only.

This feature lets the shopper submit a new contact registration request by providing
required business details through the store user interface.
To submit a new contact registration request using the store, do the following
• Login and a Register user interface will appear
• Select Join an existing business account
• Enter the following information in the Register user interface:

26-24
 Chapter 26
Understand working with contact registration requests

– First name of contact

– Last name of contact
– Email address of contact
– Account ID
– Any comments to be added to the request (entered in the Note field)
• Click Submit to submit the request or click Cancel if you wish to cancel the request.
Once a contact request has been submitted, the administrator can go to the Registration
Requests area in the Accounts area and view, update, accept, and reject contact registration
requests. A business user with Administrator or Account Manager role can view, update,
accept, and reject registration requests in the Accounts area. A Delegated Administrator can
perform the same functions using the Contact Registration Requests widget on the
Storefront.

Understand working with contact registration requests

When a shopper submits the required information for the contact registration request, an
Administrator sees the new registration request in the Contact Requests area of the Accounts
page, and can view, search, and work with contact registration requests there.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Both Contact Requests and Account Requests menu items appear as sub-items under
Registration Requests in the Accounts navigation page in the administration user interface.
Anyone with the Administrator and/or Account Manager Role can view, update, accept, and
reject registration requests.
Note: The Contact Requests tab always appears in the user interface. The Account
Requests tab will not appear if Account Registration is disabled in Settings and there are no
account registration requests with a status of New, Review, More Info Needed, or Rejected.
After the initial submission of the required details by the shopper, the contact registration
request is reviewed from the merchant side by the administrator (or delegated administrator).
At this point, the administrator (or delegated administrator) may also request from the
shopper additional details such as credit checks and more. Upon receipt of all the requested
information, the administrator (or delegated administrator using the appropriate widgets on
the storefront) then either approve or reject the registration request. If the request is
approved, the new contact with the account is activated and can then begin transacting
business.

Work with the contact registration request list

The information in the new contact registration request list can be looked at by both
Administrators and Delegated Administrators. The information that follows describes the
differences in the information that is available to each separate Role.
Via the administration user interface, the new contact registration request list for
Administrators in the Contact Requests area of the Accounts page provides the following
information in a list divided into the following:

26-25
 Chapter 26
Understand working with contact registration requests

Column Head Description

Request ID Request ID generated by the system. This
provides a link that opens the request details.
Requested Account ID Account ID that the requester provided
Requested Account Name Account Name that the requester provided
Email Address Email address that the requester provided
Last Name Last name that the requester provided
First Name First name that the requester provided
Originating Site Site on which the request originated
(Site name - or, if name is unavailable, Site ID)
Request Date Date when the request was received. (No
timestamp is provided)
Status Displays Status icon (for statuses of “Rejected”
and “More Info Needed”)
The Status of a request can be either New (the
request is new and has not been viewed),
Review (the request has been viewed or
changed and needs to be acted upon), More
Info Needed (the request has been viewed and
an action needs to be taken to collect more
account or shopper information before the
request is approved or rejected), or Rejected
(the contact registration request has been
rejected and no contact has been activated).
The status is the same regardless of which
Admin is viewing it.

You can also do the following with the new contact registration request list:
• Filter the list by status. The default view of the list is to show all statuses.
• Use a typeahead search box. The placeholder text in the box is “Search for
registration request.” When you type a string, the list is filtered to records
containing that string in the Company field.
• Sort the list by the following:
– Email address: A-Z or Z-A
– First name: A-Z or Z-A
– Last name: A-Z or Z-A
– Request date: Newest or Oldest
– Request ID: A-Z or Z-A
– Requested account name: A-Z or Z-A
The default sort order is by Request date: Newest.
• Look at other pages of the list as the list is paginated as the list grows longer.

Column Head Description

Request ID Request ID generated by the system. This
provides a link that opens the request details.
Email Address Email address that the requester provided

26-26
 Chapter 26
Understand working with contact registration requests

Column Head Description

Last Name Last name that the requester provided
First Name First name that the requester provided
Originating Site Site on which the request originated
(Site name - or, if name is unavailable, Site ID)
Request Date Date when the request was received. (No
timestamp is provided)
Status Displays Status icon (for statuses of “Rejected”
and “More Info Needed”)
The Status of a request can be either New (the
request is new and has not been viewed),
Review (the request has been viewed or
changed and needs to be acted upon), More
Info Needed (the request has been viewed and
an action needs to be taken to collect more
account or shopper information before the
request is approved or rejected), or Rejected
(the contact registration request has been
rejected and no contact has been activated).
The status is the same regardless of which
Admin is viewing it.

The Delegated Administrator can also do the following with the information that they are
allowed to view:
• Filter the list by status. The default view of the list is to show all statuses.
• Use a typeahead search box. The placeholder text in the box is “Search for registration
request.” When you type a string, the list is filtered to records containing that string in the
Company field.
• Sort the list by the following:
– Email address: A-Z or Z-A
– First name: A-Z or Z-A
– Last name: A-Z or Z-A
– Request date: Newest or Oldest
– Request ID: A-Z or Z-A
The default sort order is by Request date: Newest.
• Look at other pages of the list as the list is paginated as the list grows longer.

Search for a specific registration request

As an Administrator in the Contact Request list view, you have access to Advanced Search in
the administrator user interface via a typeahead search box.
Note: This functionality is not available for Delegated Administrators in the store’s
Registration Requests widget.
The placeholder text is “Filter contact requests.” When you type a string, the Contact Request
list is filtered to records containing that string in the Last Name field.

26-27
 Chapter 26
Understand working with contact registration requests

You can also use an Advanced Search control (same as found in the accounts,
contacts, and contact registration user interfaces to search for contact registration
requests by creating expressions like the following:

<property 1> contains <value 1>

<property 2> contains <value 2>
...
<property 5> contains <value 5>

You can also specify “Match Any” or “Match All.”

The properties available for this type of search must be:
• Of type string OR
• A custom string property of a contact registration request, account, or profile OR
• Queryable static string properties that include:
– Last Name
– Email Address
– First Name
– Contact Registration Request Property ID
– Request ID
– Requested Account ID
– Requested Account Name
– Approver Comments
– Notes from the Requester
Also, the Advanced Search control feature presents you with dropdown lists of two
groups of properties with the headers Contact and Request.
The group and the order of the properties for each header are as follows:
• Under the Contact header:
– The Contact static properties listed above, in alphabetical order
– Any Contact dynamic properties, in alphabetical order
• Under the Request header:
– The Request static properties listed above, in alphabetical order
– Any Request custom properties, in alphabetical order
When you use the extended search control, keep in mind the following:
• The first row is populated with the “Last Name” property.
• The “contains” operator is not shown; it is implicit.
• Multiple terms with the same property are supported.
• “Match All” is the default.
• When an extended search is in effect, the text, “Advanced Search Results Shown”
appears in the search box.

26-28
 Chapter 26
Understand working with contact registration requests

• After you perform an extended search, the next time you open the Extended Search
control, the criteria from your last search is displayed. This is true even if you have
performed simple searches since performing the extended search. The criteria persist
until you perform another extended search.
• The Extended Search control allows at most 5 criteria.
You cannot search for registration requests via store APIs.

View and edit contact registration request details

Contact registration request details be looked at and/or edited by both Administrators and
Delegated Administrators. Administrators use the Contact Requests area of the Accounts
page in the administrator’s user interface to view, search, and work with contact registration
requests. A Delegated Administrator can perform the same functions using the Contact
Registration Requests widget on the store.
The information that follows describes the differences in the information that is available for
viewing and editing for each separate Role.
To look at and/or edit an actual new or existing contact registration request as an
Administrator, click the Request ID (which is a link) of the request found in the Contacts
Requests area of the Accounts page. When you do that you see a detail view that combines
the following information:
• Data received from the requester
• All custom contact self-registration request properties
• Selected static contact (profile) properties
• All custom contact (profile) properties
Each request displays two tabs of information: Request and Contact. Some of the fields on
the tabs can be viewed and some can be edited. The following contains more details on the
information found on each tab:
• Request tab containing the following fields:
– Status – A dropdown list that can be used to change the status of the requests. The
choices are New, Accept, Reject, More Info Needed, and Review.
The dropdown shows New when the request is first opened. Once the status changes, the
New status is removed from the dropdown. If the profile has been deleted, the Status can
only be changed to Reject.
This field is Editable except if the Status is Rejected it becomes read-only. Also, if the contact
has been deleted, the Status can only be changed to Rejected.
• Request ID - Read-only.
• Request Date - Read-only in the user interface but editable via API.
• Site Where Request Originated - URL, Read-only in the user interface but editable via
API.
• Notes from the requester - Read-only in the user interface but editable via API.
• Rejection comments - Read-only in the user interface but editable via API. Displayed only
if the request was rejected.
• Any custom properties that exist – Editable unless the Status is Rejected.
• Contact tab containing the following fields:

26-29
 Chapter 26
Understand working with contact registration requests

Note: This tab is grayed out if the profile has been deleted. This would occur either via
the Agent API (for GDPR reasons) or because the request was rejected and the
contact was new.
• First Name – Read only. For an existing contact, the First Name stored in
Commerce takes precedence over the submitted First Name and is displayed
here.
• Last Name – Read only. For an existing contact, the Last Name stored in
Commerce takes precedence over the submitted Last Name and is displayed
here.
• Email/Login ID – Read-only.
• Requested Account ID - Read-only in the user interface but editable via API.
• Requested Account Name - Read-only in the user interface but editable via API.
• Account Name - Accessed via the picker. Editable unless the status is Rejected.
This is the name of the account to which the contact will actually be added. This
name will be pre-populated in the field with the requested account if the system
identified the account.
• Any custom properties that exist – Editable unless the Status is Rejected. If the
email address is that of an existing contact, the existing contact’s property values
take precedence over the submitted values and are the ones displayed.
If you click Cancel, any changes you have made are discarded. The Save button
applies changes made in all tabs.
Note: The previous fields described list fields that are displayed in the administration
interface. The following fields can be edited only in the REST API:
• approverComments (listed above as Rejection Comments, but the field is also
editable by API on an approved request)
• approvedBy
• approvedSource
As a Delegated Administrator, you can look at and/or edit the following information in
a contact request that you are working on. Each request displays two tabs of
information: Request and Contact. Some of the fields on the tabs can be viewed and
some can be edited. The following contains more details on the information found on
each tab:
• Request tab containing the following fields:
– Status – A dropdown list that can be used to change the status of the
requests. The choices are New, Accept, Reject, More Info Needed, and
Review.
The dropdown shows New when the request is first opened. Once the status changes,
the New status is removed from the dropdown. If the profile has been deleted, the
Status can only be changed to Reject.
This field is Editable except if the Status is Rejected it becomes read-only. Also, if the
contact has been deleted, the Status can only be changed to Rejected.
• Request ID - Read-only.
• Request Date - Read-only in the user interface but editable via API.

26-30
 Chapter 26
Work with contact requests to review, change status, approve, and reject

• Site Where Request Originated - URL, Read-only in the user interface but editable via
API.
• Notes from the requester - Read-only in the user interface but editable via API.
• Rejection comments - Read-only in the user interface but editable via API. Displayed only
if the request was rejected.
• Contact tab containing the following fields:
Note: This tab is grayed out if the profile was deleted. This would occur either via the Agent
API (for GDPR reasons) or because the request was rejected and the contact was new.
• First Name – Read only. For an existing contact, the First Name stored in Commerce
takes precedence over the submitted First Name and is displayed here.
• Last Name – Read only. For an existing contact, the Last Name stored in Commerce
takes precedence over the submitted Last Name and is displayed here.
• Email/Login ID – Read-only.
If you click Cancel, any changes you have made are discarded. The Save button applies
changes made in all tabs.
Note: The previous fields described list fields that are displayed in the Delegated
Administrator user interface. The following fields are editable via API:
• approverComments (listed above as Rejection Comments, but the field is also editable by
API on an approved request)
• approvedBy
• approvedSource

Work with contact requests to review, change status, approve,

and reject
Submitted contact registration requests can be seen in the Contact Requests area of the
Accounts page.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The following information provides an example of an Administrator’s or Delegated

Administrator’s change/approval/rejection process that occurs when working with a new
contact registration request. When a new contact request is received, the request enters the
system with a status of New until you either change the status of the request and save it, or
you open the request without changing it.
• If you save changes that do not include a status change
– If an error occurs you receive an error message and the detail view is kept open.
– If the save is successful and the status is New, the status is then changed to Review.
If there is an exception with provided addresses, then there may have to be some
editing done in another dialog. Finally, the detail view closes and you are returned to
the list view.
• If you choose Accept from the status dropdown list while making a status change and
have clicked Accept to confirm the choice:

26-31
 Chapter 26
Work with contact requests to review, change status, approve, and reject

– You are given the option to provide comments that are added to the
acceptance email sent to the shopper who made the request. The comments
are limited to 1000 characters.
– Validations are performed on the information if it is accepted.
– If there is an error, an error message is displayed and you are returned to the
details view.
– If there are no errors, the contact is added to the account. The detail view is
closed and you are returned to the list view. The request is removed from the
list view.
– If the contact is new, it is activated. If it is an existing active contact, it is left
active. If it is an existing inactive contact, it is left inactive.
– An approval email is sent to the shopper who submitted the request.
– If you click Cancel on the confirmation dialog, you are returned to the detail
view.
• If you select Reject from the status dropdown list:
– You are given the option to provide comments that are added to the rejection
email sent to the shopper who made the request. The comments are limited to
1000 characters.
– Validations are performed on the information that is rejected.
– If there is an error, an error message is displayed and you are returned to the
details view.
– If there are no errors, the status is changed to Rejected.
– The detail view is closed and you are returned to the list view.
– The rejected request is kept in the list.
– All fields in the request are made read-only.
– In the details view, The “Contact” tab is grayed out (unless the contact is an
existing contact).
– The shopper who submitted the request is sent a rejection email.
– You must clean up the entry after it is rejected. When a contact request is
rejected, you can hard delete the pending contact and organization. Do not
delete the contact if it is an existing contact.
– If you click Cancel on the confirmation dialog, you are returned to the detail
view.
A contact self-registration request does not ever need to have a Review or More Info
Needed status. You can open a new request, make changes, change the status to
Accept or Reject, and Save. In the example just described, the contact request goes
from New to Rejected, or from New to adding the contact to the account.

Store the source of an approval or rejection

When a request is approved or rejected, Commerce stores the value of a source
property that indicates where the approval or rejection came from. These are the
options:
• If the administrator approved or rejected the request in the administrator user
interface, the system, “Administrator” is stored as the source.

26-32
 Chapter 26
Delete contact information

• If the request was approved or rejected using the Admin endpoint, Commerce stores
“Administrator” as the source by default, or stores any string value provided in the call.
• If the request was approved or rejected in the store user interface or by the store API,
Commerce stores “Delegated Administrator” as the source.
• If the request was approved or rejected in the Agent user interface or by the Agent API,
Commerce stores “Agent” as the source.
• If the request was approved or rejected by an external system, Commerce stores the
string value provided in the call (if provided).
Note: Source values that are provided are not localizable.

Understand more about working with contact requests

The following provides some additional information about working with contacts and new
contact registration requests:
• There is only one version of a contact. Therefore, an update to a contact’s details made
in one place (the Accounts user interface, the Account Registration user interface, or the
Contact Registration Request user interface) appears in all the user interfaces.
• Re-using a contact with a pending contact registration request - If a shopper who is not
yet a business account contact has a contact registration request pending, and the
Administrator or Delegated Administrator wants to add the shopper to an existing
account, the Merchant Administrator must either approve the request and then add the
contact, or reject the request and then create the new contact.
If the Merchant Administrator tries to create a new contact, and the email address is that of a
contact registration request pending, the message, “The email address you entered has a
pending contact registration request. To add the user to an account, you must first approve or
reject the request” is displayed.
If the Delegated Administrator tries to create a new contact, and the email address is that of a
contact registration request pending, the message, “The email address you entered has a
pending contact registration request. You or the merchant must accept or reject the request
before you can add the user to an account” is displayed.
In a configuration where account-based shoppers and registered non-account-based
shoppers coexist, if a shopper (or an API) tries to create a new registered non-account-based
shopper profile using an email address that has a pending business account contact
registration request, the message: “You cannot use this email address at the moment. Please
contact the system administrator” is displayed
• Cleaning up after a rejected request and re-using the contact - When a registration
request is rejected, you must hard delete the pending contact. (Do not delete the contact
if it is an existing contact.). After that is done the email address (username) of the contact
is now free for re-use for a new business account contact and registered non-account-
based shopper contact.

Delete contact information

When you delete a contact’s profile to comply with the European Union General Data
Protection Regulation (GDPR) right to erasure, you must also remove personal information
about the contact that appears in orders and other items, such as purchase lists.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

26-33
 Chapter 26
Delete contact information

You should redact these account-based commerce items before deleting the contact’s
profile.
This section describes how to prepare for deleting a contact’s profile and delete or
redact account-based commerce items that contain the contact’s personal information.
See Delete shopper information for information about deleting profiles for contacts,
redacting orders, and redacting registration requests.

Delete purchase lists as an agent or administrator

Purchase lists (personal or shared) let shoppers quickly access frequently purchased
items. If a contact has created (and possibly shared) purchase lists, delete them
before you delete the contact’s profile. You can delete purchase lists in the Commerce
Agent Console or with the Agent API. Keep in mind the following:
• You (the Administrator) should ask the person to delete any purchase lists she
created, before you delete their profile.
• The Commerce Agent Console or the Agent API can be used to delete the list
even if the purchase list is shared.
• When a shared purchase list is deleted, the recipients of a shared list do not
receive an email notification.
• To delete a purchase list in the Agent Console, find the contact’s profile page and
click the Purchase Lists tab. See View customer results in Search for customers
for more information.
• To delete a purchase list with the Agent API, use the deletePurchaseList
endpoint. (If for business reasons you do not want to delete purchase lists, you
can redact them instead.) See Delete or redact purchase lists in Delete shopper
information for more information.
See Enable Purchase Lists for details about purchase lists and shared purchase lists.

Prepare to delete the profile for an approver

The order approvals feature for account-based storefronts lets administrators enable
order approvals for an account and specify a purchase limit. When a contact within the
account creates an order that exceeds the purchase limit, the order is sent to an
approver for confirmation before it is submitted.
If a contact is assigned the Approver role, they can approve orders for their account.
Before you delete the profile for a contact who is an approver, perform the following
tasks:
• Remove the Approver role from the contact for all accounts before deleting the
profile. (A contact’s profile cannot be deleted if the contact has the Approver role
for any account.) See Manage approvers for an account for more information.
Important: Make sure each account still has at least one approver left. You cannot
remove the Approver role from the last approver on the account or deactivate the last
approver on the account if there are orders pending approval or the order approval
feature is enabled.
• Use the Admin API to remove the approver’s ID from all orders they approved
using the Admin API. See Delete an approver in Delete shopper information for
more information.

26-34
 Chapter 26
Delete contact information

Deactivate scheduled orders

Scheduled orders let shoppers create an order and a schedule that determines the frequency
used to fill the order in the future. If a contact has created scheduled orders, deactivate them
before you delete the contact’s profile so that the orders will no longer be placed. Once
scheduled orders are deactivated, you can either delete or redact them. See Delete or redact
scheduled orders in Delete shopper information for more information.
You can deactivate scheduled orders in the Commerce Agent Console or with the Agent API:
• To deactivate a scheduled order in the Agent Console, find the contact’s profile page and
click the Scheduled Orders tab. See Schedule an order in Understand punchout orders
for more information.
• To deactivate a scheduled order with the Agent API, use the updateScheduledOrder
endpoint. See Understand Extension Features for details about using the REST APIs.
See Create Scheduled Orders for details about scheduled orders.

26-35
27
Create Page Layouts that Support Different
Types of Shoppers
Commerce supports different types of shoppers including anonymous shoppers, individual
shoppers and account-based shoppers.
The page layouts that you create must take these shoppers types into account and present
UI features that are appropriate for their tasks.
Note: The account-based commerce feature may not be enabled in your environment.
Contact your Oracle account manager for more details on how to activate this functionality.

Understand the different types of shopper

Different types of shoppers, for example, shoppers with personal or business accounts, can
have different experiences on your storefront.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Commerce supports several types of shopper.

• Anonymous shoppers have not logged in and are not associated with a saved profile.
These shoppers are also called guest shoppers.
• Registered shoppers are shoppers who log in to a personal account. These shoppers are
allowed to self-register and manage their own billing and shipping addresses.
• Account-based shoppers are shoppers who log in using contact credentials that have
been defined as part of a business account. They use account-level billing and shipping
addresses that have been created by a merchant administrator. Account-based shoppers
need to be given special roles in order to create and manage personal addresses, and/or
create and manage account-level addresses. Refer to Work with account contacts and
Work with account addresses for more information.
Account-based shoppers can be added to a business account by an administrator in
Commerce. There is also an option for an account-based shopper to submit a new account
registration request which is then either approved or rejected by an administrator for the
account. The shopper requests a new account by providing required business details. After
submitting the required details, the information is reviewed by an account administrator. If
needed, there may also be a request for additional details such as credit checks and other
information. The request is then either approved or rejected. If the request is approved, the
new contact with account is activated and can then begin transacting business with the
account. After the shopper has been approved, they become an account-based shopper who
logs in using contact credentials that have been defined as part of a business account. Refer
to Configure Account-based Shoppers and Configure Business Accounts for more details.
In Commerce, an anonymous shopper can browse and add items to her cart. The
anonymous shopper will see products in the default catalog and prices from the default price
list group. Registered shoppers will also see products from the default catalog and default

27-1
 Chapter 27
Create cloned layouts

price list group, while account-based shoppers will see the catalog and price list group
assigned to their business account.
If an anonymous shopper logs in to a business account, the login triggers a
comparison between the items in the shopper’s cart and the products available in the
business account’s assigned catalog. If items exist in the cart that are not present in
the business account’s catalog, those items are removed and the shopper is notified.
If an anonymous shopper logs into a personal account, no comparison is necessary
because anonymous shoppers and registered shoppers use the same catalog and
price list group.
Understanding the types of shoppers your storefront must support is critical to
designing page layouts properly and making appropriate choices about the widgets
you use. The following sections describe settings you can use to control the storefront
experience for different types of shoppers.

Create cloned layouts

As you create your layouts to support different types of shoppers, remember that
Oracle recommends that you avoid modifying the out-of-the-box page layouts.

This section applies to Storefront Classic only.

Instead, create clones of those layouts and modify them. As you modify your page
layouts, keep in mind the following questions for each type of shopper your storefront
supports:
• Which types of shopper should be able to view the layout? For example, do you
need one version of a layout for anonymous shoppers and a second version for
account-based shoppers?
• Does the layout contain content that is inappropriate for a given type of shopper?
For example, if your storefront requires a shopper to log in before being able to
see the catalog or search for items and add them to the cart, then you should
consider a layout for anonymous shoppers that removes access on the Home
page to catalog, search, and cart information.

Restrict guest checkout

Your site can require that anonymous shoppers log in before they check out.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This feature can be used for anonymous shoppers who will log into either an individual
account or a business account.
To prevent guest checkout:
1. Click the Settings icon.
When running multiple sites from your Oracle Commerce instance, your
configurations will be applied by site. Choose your site from the site picker at the
top of the Settings menu options.
2. Click Shopper Settings.
3. Under Guest Checkout, clear the Allow checkbox.

27-2
 Chapter 27
Manage pages for account-based shoppers

In addition to selecting this setting, your pages must be modified at a widget code-level to
restrict access to the Checkout UI itself. For details on doing so, see Manage Guest
Checkout.

Manage pages for account-based shoppers

This section provides guidance on how you can manage pages for account-based shoppers.

This section applies to Storefront Classic only.

Restrict a page layout to account-based shoppers

When you clone a page layout, you can configure the new layout with one of the following
options:
• “Make Default Layout” defines the layout as the default. It is this layout that is rendered
for anonymous shoppers and registered shoppers.
• “Display layout to account shoppers only” restricts the layout to account-based shoppers
only.
Using these two settings, you can design a set of layouts for your anonymous and registered
shoppers and another set for your account-based shoppers. Note that this may not be
required for all layouts; in other words, if a layout does not need different content for the
various shoppers types, you can have one default layout for all of them.

Restrict self-registration for account-based shoppers

Some out-of-the-box widgets allow self-registration while others do not. These widgets should
be used appropriately, depending on the types of shopper your storefront supports.
Specifically, shoppers should not be allowed to self-register for a business account. In the
case of a storefront that supports both individual shoppers and account-based shoppers, your
UI should make it clear that any self-registration activity creates an individual shopper
account, not a business account (see Note about preventing self-registration in account-
based storefronts for more details). The following widget elements affect self-registration:
• The Login/Registration element in the Header widget allows self-registration while the
Contact Login (for Managed Accounts) element does not.
• The Registration Button element on the Wish List Welcome widget, available on the Wish
List Layout, allows self-registration. This element can be removed for pages that must
prevent account-based shoppers from self-registering.

Restrict address editing for account-based shoppers

Some out-of-the-box widgets allow shoppers to modify their billing and shipping addresses
while others do not. In account-based storefronts, addresses are managed at the account
level and shoppers should not be allowed to modify them. As such, these widgets should be
used appropriately, depending on the types of shopper your storefront supports. The following
widgets affect address editing:
• The Customer Address Book widget, on the Checkout Layout and Checkout Layout with
GiftCard layouts, allows address creation and editing. By contrast, the Account Address
Book widget on these layouts allows a contact to choose an address from those defined
for the account and to specify a person to ship to but further editing of the address is not
available.

27-3
 Chapter 27
Configure page layouts for account hierarchies

• The Customer Profile Widget on the Profile Layout allows customers to edit their
billing and shipping addresses. To restrict address editing, account-based
storefronts must create a new profile widget that displays profile information but
does not enable address editing. For details on creating the new profile widget,
see Manage account-based shopper profiles.

Ensure account-specific catalogs and price groups are displayed for account-
based shoppers
When they are created, business accounts are assigned a catalog and price group. In
the storefront, account-based shoppers should be shown the catalog and price group
assigned to their business account. To ensure that the correct catalog and price group
is shown to an account-based shopper, you must use the latest version of the
Collection Navigation widget on the Home Layout and the Shopping Cart widgets on
the Cart Layout. Server side code automatically determines which catalog and price
group to show and passes it to the storefront. The storefront then displays the catalog
and price group it has been passed, via these two widgets. For instructions on how to
check which version you are using, see Design Your Store Layout. If you are not using
the latest version, you must upgrade to it. See Upgrade deployed widgets for
instructions on how to do so.

Display company name and logo to account-based shoppers

There are two places where you can choose to add a company name and logo to an
account-based storefront:
• To the header in the storefront page layouts, using the Company Name and
Company logo elements in the Header widget.
• To the email templates used to generate automated email notifications. See the
Add company name and logo to account-based email templates section in
Customize Email Templates for details on how to do this.

Configure page layouts for account hierarchies

Account hierarchy allows you to configure your storefront so that changes that you
make to one account can be seen by other accounts.

This section applies to Storefront Classic only.

Oracle recommends that you clone the out-of-the-box layouts and then make your
changes to the clones. If your site only supports account-based shoppers, you can
mark the clones as the defaults and make the account hierarchy changes to those
pages. If your site must support both account-based shoppers and other, non-account
affiliated shoppers, then you will need two versions of the pages, one marked as
default for the non-account affiliated shoppers and the other marked as “Display layout
to account shoppers only” for the account-based shoppers. In this scenario, you would
make the account hierarchy changes to the pages designed for the account-based
shoppers.
See Configure Business Accounts to learn how to create an account hierarchy and
assign contacts to multiple accounts.
The modifications described in the sections below involve making sure you are using
the correct version of some of the out-of-the-box widgets. A widget’s About tab,

27-4
 Chapter 27
Manage page layouts to support account and contact registration requests

accessed by viewing a widget’s settings, tells you which version you are using. To replace a
widget with the latest version, see Upgrade deployed widgets.

Header widget for account hierarchies

Make sure you are using version 6 or later of the Header widget on all pages that use it. Also,
make sure the Contact Login (for Managed Accounts) element is included in your Header
widget instance. This element provides a picker that allows an account-based shopper to
switch to any active account he belongs to.

Checkout layout for account hierarchies

On the Checkout layout, make sure you are using version 3 or later of the Managed Account
Address Book widget. This version allows the account-based shopper to view default, local,
and inherited account-level addresses when specifying the billing and shipping address for
the order.

Profile layout for account hierarchies

On the Profile layout, make sure you are using the correct versions of the following:
• Account Addresses widget (version 3 or later). This version allows the delegated
administrator to view an account’s default, local, and inherited addresses.
• Account Contacts widget (version 3 or later). This version does the following:
– Informs the delegated administrator if a contact belongs to multiple accounts.
– Prevents the delegated administrator from deactivating a contact if the contact
belongs to multiple accounts.
– Limits the delegated administrator to removing a contact from the current account
only.
The Account Addresses and Account Contacts widgets are described in Add delegated
administration to your storefront.

Order Details and Scheduled Order layouts for account hierarchies

On the Order Details layout, make sure you are using one of the following:
• Version 6 or later of the Order Details widget, or
• Version 4 or later of the Order Details with Additional Info widget
These versions prompt the shopper to switch accounts if she attempts to view details for an
order that was placed under an account other than the one she is currently logged into.
For the same reason, make sure you are using version 3 or later of the Scheduled Order
widget on the Scheduled Order layout if your storefront includes the scheduled orders
feature. See Create Scheduled Orders for more information.

Manage page layouts to support account and contact

registration requests
You can allow a prospective account-based shopper to request registration of a new store
account.

This section applies to Storefront Classic only.

27-5
 Chapter 27
Manage page layouts to support account and contact registration requests

Enabling this feature lets a shopper submit an account registration request for a new
account by providing required business details. The information is then reviewed by an
administrator from the merchant side after the shopper submits the required details,
and, if needed, the administrator may request additional details such as credit checks.
The account registration request is then either approved or rejected. If the request is
approved, the new contact for the account is activated. Refer to Configure Business
Accounts to learn more about account registration requests.
You can also allow an existing account-based shopper (contact) or a registered non-
account-based shopper to submit a contact registration request. A registered non-
account-based shopper can be defined as a shopper with an email address that is not
registered. An existing account-based shopper would have an email address that was
registered as part of their role as an account-based shopper. The contact request
process feature lets a shopper submit a request to be added as a contact to an
existing business account by providing required contact and account details. The
information is reviewed by an administrator or a delegated administrator from the
merchant side after the shopper submits the required details. If needed, the
administrator may request additional details from the shopper such as credit checks.
The contact registration request is then either approved or rejected. If the request is
approved, the new contact for the account is activated and added to the account.
Refer to Configure Business Accounts to learn more about contact registration
requests.
To manage and configure page layouts for account-based shopping that supports
account registration requests and contact registration requests, do the following:
• Enable the store user interface to allow business shoppers to submit an account
registration request for a new account by providing required business details. Do
this by making sure you have a Contact Login (for Managed Accounts) element in
the Header widget in your site Home layout. That way, when an anonymous
shopper or an account-based shopper logs in, a Contact Login (for Managed
Accounts) element displays a Register link that allows the shopper to submit
contact registration requests. For further details, refer to Customize your store
layouts for information on using different elements in your layouts.
• Make sure you have enabled the account registration feature in the Settings area
of Administrator user interface. Refer to Configure Account-based Shoppers in the
Configure Shopper Settings section for more details.
• Configure the correct automated emails that are generated during the account
registration request and contact registration request approval/rejection process.
Refer to Configure Email Settings for more information.
• If you want Delegated Administrators to be able to manage contact registration
requests, add the Contact Registration Requests layout to the Profile Navigation -
Account Shoppers widget, and configure the layout to appear to shoppers with the
Administrator role.

27-6
28
Use Order Approvals
Commerce includes an order approvals feature for account-based storefronts.
This feature allows an administrator to enable order approvals for an account and specify a
purchase limit. When a contact within the account creates an order that exceeds the
purchase limit, the order is sent to an approver for confirmation before it is submitted.
You can also integrate with an external system that determines if an order requires approval.
This is useful if you want to use the system to create more complex rules than a simple
purchase limit to determine if an order requires approval. For example, you might want all
orders that include specific items or that are shipped to certain addresses to require approval.
See Enable Order Approvals to learn how to integrate with an external system for order
approvals.
The sections in this chapter describe how to accomplish various order approval-related tasks
in both the Commerce administration interface and the storefront. Note that, for the storefront
tasks, this section assumes that order approvals have been properly configured on the
storefront side. For details on how to do this, see Enable Order Approvals.

Understand order approvals

When a shopper places an order that requires approval, that order is not submitted until the
approval has been given.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Approvers are notified, via email, when orders come in that require approval. An approver
can log in and see all orders that require approval for their account.
If the order is approved, what happens next depends on the type of payment method the
shopper needs to use. Commerce cannot store credit card information, so it cannot maintain
credit card information for the time period in between when the order is placed and when the
order is approved. Therefore, if the shopper needs to use a credit card for payment, she must
return to the order’s details after the order has been approved and provide credit card
payment information. The amount of time the shopper has to make payment on an approved
order is configured via the Price Hold Period, described in Set a price hold period. Other than
payment information, the shopper should not be able to modify any other order details.
Limiting the shopper’s order editing ability requires some customization of the checkout
layout, described in Manage the checkout flow for orders requiring approval.
If the shopper used a deferred payment method like invoice or cash when placing the order,
no additional payment details are needed and the order is submitted immediately upon
approval.
When an approver approves an order that needs payment, an email is sent to the shopper
notifying her that the order has been approved and she should provide payment information.
When an approver approves an order that does not need payment, the standard order placed
email is sent to the shopper, telling her that the order has been submitted.

28-1
 Chapter 28
Enable or disable order approvals

If the approver rejects the order, the shopper is notified via email. Rejected orders
cannot be modified or re-submitted. However, the shopper can view the rejected
order’s details and add its items to a new shopping cart to form the basis of a modified
order that can pass approval.

Enable or disable order approvals

Order approval settings are defined at the account level and apply to all contacts
within the account.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The order approval feature can be enabled or disabled either in the administration
interface or on the storefront, but not both. If you configure the order approval settings
from the storefront, the corresponding settings in the administration interface become
read-only.
Note: This section describes how to enable or disable the order approval feature when
you set a purchase limit in Commerce. To set upCommerce the order approval feature
using the Order Approval webhook to integrate with an external system, see Enable
Order Approvals.
Order approvals can only be enabled if at least one contact in the account has the
Approver role. See Manage approvers for an account for details on how to assign that
role. When order approvals are disabled, the change only affects new orders. Existing
orders that require approval continue to require approval.
To enable or disable order approvals in the administration interface:
1. Click the Accounts icon.
2. Select the account to be modified.
3. Click the Approvals tab.
4. If you are using multiple sites, select the name of the site. Approvals are site-
specific.
5. If you are using an external approval system, select the Use external service to
determine approval settings check box. Note that when this option is selected, the
default Require Approval option is disabled.
6. Enable the Require approval option and set the purchase limit above which orders
require approval. See Understand the purchase limit for order approvals for more
details.
Before you can enable order approvals from the storefront, you must set an option in
the administration interface that gives control of the order approvals setting to the
storefront administrator. Note that when you set the option, the order approvals
settings in the administration interface become read-only.
To enable or disable order approvals in the storefront:
1. Click the Accounts icon.
2. Select the account to be modified.
3. Click the Approvals tab.
4. If you are using multiple sites, provide the name of the site, as approvals are site-
specific.

28-2
 Chapter 28
Understand the purchase limit for order approvals

5. Enable the administrator at the account can manage approvals option and click Save.
6. On the storefront, log in as an administrator.
7. Click the My Account link.
8. Click the Order Approval Settings tab.
Note: The Order Approval Settings tab must be configured on the storefront before you
can use it and it also may use a different name if your implementation team chose to use
a different one.
9. Enable the Require Approvals option and set the purchase limit above which orders
require approval. See Understand the purchase limit for order approvals for more details.

Understand the purchase limit for order approvals

The purchase limit sets a value.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Orders that exceed this value require approval. If a purchase limit is not defined, no orders
require approval. If a purchase limit is set to 0, all orders require approval. There is one
purchase limit for the entire account and it applies to all contacts in the account, regardless of
role (buyer, approver, or administrator). The currency for the purchase limit value is
determined by the price list group associated with the account’s contract. In other words, if an
account’s contract is associated with a price list group that uses Euros, then the purchase
limit is also in Euros.
If an account has multiple contracts, you must select a site when setting a purchase limit. The
purchase limit applies to any orders submitted by buyers on the associated site.
Note: Display of a contact’s purchase limit is not included in the out-of-the-box widgets,
however, you can write custom widget code to display this information. See Display a
contact’s purchase limit in a widget for more information.

Set a price hold period

You can set a price hold period, after which an approved order that is pending payment is
canceled by the system.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The time count starts from when an order is approved. The notification email that is sent to a
shopper after an order is approved includes an expiration date and time that is based on the
price hold period. The shopper must pay for the order by this expiration date and time.
After the specified amount of time has passed, the order is marked for cancellation. To handle
the actual removal of these orders, a scheduled service runs that identifies orders that have
been marked for cancellation and then removes them. See Set the frequency of canceled
order clean up for more information on this service.
The price hold is site-specific and applies to all accounts. The default setting is that there is
no time limit. An order that has been canceled because of the time limit has a “Removed”
status, which is the same as any other canceled order. Coupons that have been redeemed as
part of a canceled order are not released.
To set the price hold period:

28-3
 Chapter 28
Manage approvers for an account

1. Click the Settings icon.

2. Select the Site.
3. Click Payment Processing.
4. Click the Setup tab.
5. Enter a number of days and hours for the Price Hold Period and click Save.
Note: When the Price Hold Period is modified, the new time limit applies to all orders,
existing and new. This means that the expiration date and time that a contact sees in
the “Order Approved” notification email may become stale if the time limit has been
changed after the contact has viewed the email. See Notify users of order approval-
related events for more information about the “Order Approved” notification email.

Manage approvers for an account

You must assign the Approver role to users you want to be able to approve orders.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

An approver can:
• View all orders requiring approval for their account.
• Approve any order requiring approval, including those that were submitted before
the approver was assigned the Approver role.
• Approve their own orders.
An administrator assigning roles:
• Can assign the Approver role to himself.
• Cannot remove the Approver role from the last approver on the account or
deactivate the last approver on the account if there are orders pending approval or
the order approval feature is enabled.
To assign the approver role in the administration interface:
1. In the administration interface, click the Accounts icon.
2. Select the account to be modified.
3. Click the Contacts tab.
4. Select the contact you want to assign the Approver role to, click the Approver role,
then save the contact.
To assign the approver role in the storefront:
1. On the storefront, log in as an administrator.
2. Click the My Account link.
3. Click the Account Contacts tab.
4. Select the contact you want to assign the Approver role to, click the Approver role,
then Save the contact.

28-4
 Chapter 28
Understand how approvers approve and reject orders

Understand how approvers approve and reject orders

Order approval and rejection happens on the storefront, after order approval has been
enabled and orders have been submitted that require approval.

This section applies to Storefront Classic only.

An approver can see a list of all orders pending approval, even those that were created
before he became an approver.
To approve or reject orders:
1. On the storefront, log in as an approver.
2. Click the My Account link.
3. Click the Orders Pending Approval tab.
Note: The Orders Pending Approval tab must be configured on the storefront before
you can use it and it also may use a different name if your implementation team chose to
use a different one. See Allow a delegated administrator to control order approvals for
more information.
4. Click the order ID to view the details for an order that needs approval.
5. Provide any optional comments and then click either Reject or Approve to reject or
approve the order, respectively. An email notification is sent to the shopper after an order
has been approved or rejected.

Understand the effect of order approvals on scheduled orders

A scheduled order requires approval if one instance of the scheduled order exceeds the
purchase limit.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

When a scheduled order is approved, the approval applies to every instance of the order
created based on the schedule. The approval will persist even if the prices of the schedule
order change. Conversely, if Commerce determines that a new scheduled order does not
require approval, that determination persists even if the prices change in the schedule order
and cause its total value to exceed the purchase limit at some point in the future.
The approval status of a scheduled order affects what the shopper can do with the order.
When a scheduled order has been approved, the order is locked down and the only elements
that can be edited are the schedule, the active or inactive setting, and the payment method.
Note that a scheduled order does not go back for re-approval if the schedule is edited.
When a scheduled order has been rejected, none of the order’s instances will be allowed to
proceed and the order cannot be edited. When a scheduled order is pending approval, its
contents will be repriced when the order’s details are viewed. The shopper can modify the
schedule and the active/inactive setting of a scheduled order that is pending approval.
Note: Scheduled orders that already exist when the order approval feature is enabled are
allowed to proceed without approval.

28-5
 Chapter 28
Notify users of order approval-related events

Notify users of order approval-related events

Emails are sent to approvers and shoppers to notify them of various order approval-
related events.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

You can enable or disable these emails in the administration interface (see Configure
Email Settings for more information). The order approval-related emails include the
following:
• The Order Pending For Approval email is sent to all approvers when an order is
placed that requires approval.
• The Order Approved email is sent to the shopper when an order is approved and
needs payment. Note that this email provides the shopper with an expiration date
and time, after which the order is canceled if payment has not been made. See
Set a price hold period for more information.
• The Order Placed email is sent to the shopper when an order is approved that
does not require payment. In this case, the order is submitted immediately upon
approval and the shopper is notified via the Order Placed email.
• The Order Rejected email is sent to the shopper when an order is rejected.
• The Store Cancel Order email is sent to the shopper when an order is canceled
because it exceeds the price hold period.
• The Payment Failure email is sent to the shopper when an approved order that
has been paid for encounters a payment error.
Clicking the order link in any of these emails will take the shopper or approver to the
Order Details page for the order. From this page, the approver can approve or reject
the order and provide optional comments. Also from the details page, the shopper can
provide payment for an order that has been approved. For an order that has been
rejected, a shopper can choose to add the order’s items to a new shopping cart to
form the basis of a modified order that can pass approval.
You can modify the out-of-the-box email templates so that they match your storefront’s
look and feel. See the Customize Email Templates for detailed information.

28-6
29
Run Multiple Stores from One Commerce
Instance
Your Commerce instance initially has a single site, or store; you can, however, run multiple
sites from a single Commerce instance.
Each site corresponds to a store and can have its own catalog. For example, if your company
has multiple brands, you can have one site per brand. You could also have a site whose
catalog includes items for sale in one country and another site whose catalog includes items
for sale in a different country.
This section discusses what you need to know before running multiple sites in your
Commerce instance.

Understand what is shared among sites

If you choose to run multiple sites from a single Commerce instance, you should be aware
that some content and configuration is shared among the sites and some is not.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The following list describes what is shared by all of the sites in your Commerce instance:
• Tax processors are shared by all sites, but you can assign a different warehouse ship-
from address to each site.
• A shopper’s profile is shared by all sites. This means that a shopper uses the same
credentials to log in on each site. If the shopper changes sites, he must log in each time
but he will use the same credentials. It also means that any billing or shipping addresses
added to a shopper’s profile are available to all sites.
Note that, while profiles are shared across sites, the values of certain properties in the
profile can be site-specific. See Create a shopper profile for more details.
• Translations are shared by all sites. You can, however, specify different locales for each
site.
• There is one search index for all sites and they share thesaurus entries, keyword
redirects, and searchable field ranking lists.
Features and settings not included in this list can be configured on a per site basis. For
example, catalogs, price groups, shipping methods, page layouts, promotions, email
templates, and so on can be configured on a per site basis. For site-specific information on
these features, refer to their documentation in Understand Oracle Commerce and
Understand Extension Features.

Understand what is shared among business account sites

When your environment is configured to use business accounts, a contact’s profile is shared
across sites. However, before a contact can log into a site and make purchases, the contact’s
account, must have an associated contract for each site. When you create a contract for an
account, contacts can log into the site and make purchases using the product catalog and

29-1
 Chapter 29
Define a site

prices that have been assigned to their account. To enable a contact access to any
site, the account must have a contract for the site.
Note that accounts can be associated with multiple contracts (one contract for each
site), which allows you to have accounts that span multiple sites from a single
Commerce instance.
The following account-based entities are shared across sites:
• contacts
• the contact’s roles
• addresses
• account properties, including name, location in hierarchy, status, description,
classification, type, DUNS number, Tax Reference number, Unique Identification
number, VAT reference number and the account logo
For information on working with business accounts, refer to the Configure Business
Accounts section.

Define a site
A number of tasks required for creating and managing sites in a Commerce instance
can be done in the Commerce administration UI, though other tasks, such as enabling
a site, are developer tasks that must be done via the Admin REST API.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Only users with the Administrator or Settings roles can create and manage sites. See
Configure Internal User Accounts for information about assigning roles to users.

Create a site
This section describes how to create a new site in the administration interface. Sites
you create in the administration interface are not automatically enabled. To enable a
new site, you must use the Admin REST API. See Configure Sites to learn how to
enable sites.
When you create a new site in the administration interface, you must give it a Site Title
and Site Base URL. Commerce automatically assigns it an ID, which is not visible in
the administration interface, but which you can access with the Admin REST API.
To create a new site:
1. Click the Settings icon.
2. Click the + button next to the Setup menu item to display the Create Site dialog.
3. Enter the following required information for the new site, then click Save:
Site Title: Provides the default value of the <title> tag for all your store’s pages,
including the store’s home page.
Site Base URL: Provides the base string value for absolute URL link generation,
for example, for sitemap URLs.
4. Enter additional information about the store for the new site. See Enter basic store
information for details.

29-2
 Chapter 29
View, preview, and publish sites

Change the default site

To simplify site creation, Commerce designates one site as the default site. When you create
a new site in the administration interface, you must give it a unique Site Title and Site Base
URL. Commerce automatically assigns it an ID, which is not visible in the UI. The new site
inherits all its other properties from the default site, though you can change them on the
Settings Setup page.
In addition to serving as a template for site creation, the default site is used as the destination
for requests to your Commerce instance when a URL cannot be otherwise resolved. For
example, if a shopper tries to access a store with a URL that does not match the production
URL (the primary URL for accessing the site) or any of the additional production URLs
(alternate URLs that can be used to access the site), Commerce displays the home page of
the default site.
There is always one default site in an individual instance of Commerce. Initially, this is the site
included with each Commerce instance. This site’s initial Site Title is Commerce Site and its
internal ID is siteUS. Once you have created other sites, you can change which site is the
default. A site must be enabled before you can make it the default. Sites you create in the
administration interface are not automatically enabled. To enable a new site, you must use
the Admin REST API. See Configure Sites in Configure Sites to learn how to enable sites.
To change the default site:
1. Click the Settings icon.
2. Select Setup from the list of settings.
3. Pick a site to make the default from the list that appears above the settings list.
4. On the General tab, select the Make Default Site checkbox and then click Save.

Delete a site
Deleting a site may affect many aspects of your store, including orders, reports, and a
number of store settings. You should not delete a site that is currently in use with your
production environment. You cannot delete the default site. If you want to delete the site that
is currently the default, first make a different site the default.
To delete a site:
1. Click the Settings icon.
2. Select Setup from the list of settings.
3. Pick a site to delete from the list that appears above the settings list.
4. On the General tab, click Delete.
5. Click Continue in the Warning box to confirm that you want to delete the site.
6. Click Save on the General tab.

View, preview, and publish sites

When a shopper views a site, the Commerce server detects the site from the URL and only
returns content appropriate for that site.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

29-3
 Chapter 29
View, preview, and publish sites

When you preview your sites in the administration interface, you can choose which site
to view. When you publish changes, changes you have made for all sites are
published, meaning you cannot filter the updates-to-publish list by site.

29-4
30
Accessibility Tasks
Oracle's goal is to make its products, services, and supporting documentation accessible to
all users, including users that are disabled.
To that end, our documentation includes features that make information available to users of
assistive technology. This documentation is available in HTML format, and contains markup
to facilitate access by the disabled community. Accessibility standards will continue to evolve
over time, and Oracle is actively engaged with other market-leading technology vendors to
address technical obstacles so that our documentation can be accessible to all of our
customers. For more information, visit the Oracle Accessibility Program website at http://
[Link]/us/corporate/accessibility/[Link].

About keyboard shortcuts

Commerce supports standard keyboard shortcuts that are used in many software
applications.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

In addition, the service provides its own shortcuts, which are described in this section.

Navigate the UI
The following table describes keyboard shortcuts you can use to navigate the Commerce
administration interface.

Keyboard Shortcut Result

Ctrl+` Opens the main menu.
Tab Navigates to the next focusable element.
Note: Use the right and left arrow keys to navigate
among the Home, Preview, Language, and User
icons that appear at the top right of every page in
the administration interface.
Shift+Tab Navigates to the previous focusable element.

Note: For keyboard users navigating the administration interface in Firefox on a Mac, tabbing
to the Forgot Password? link on the login screen does not work as expected. To fix this issue,
follow these steps:
1. Select System Preferences on the Mac.
2. Select Keyboard and display the Shortcuts tab.
3. Select the All Controls option.

30-1
 Chapter 30
About keyboard shortcuts

Select items
The following table describes the keyboard shortcuts you can use to select navigable
items. You can then move the selected items. For example, you might want to select
several items to move to a different collection.

Keyboard Shortcut Result

Space Selects the item that has focus.
To deselect a selected item, press Space
again.
‘t’ + ‘w’ Opens the component library within the design
layout’s Grid View.

Move and act on selected items

The following table describes the keyboard shortcuts you can use to act on selected
items.

Keyboard Shortcut Result

Down Arrow Moves selected items down in a list or grid.
Up Arrow Moves selected items up in a list or grid.
Left Arrow Moves selected items to the left.
Right Arrow Moves selected items to the right.
Enter Triggers the associated action when the focus
is on a link, image, or button.
Esc Closes the dialog that has focus.
Discards unsaved changes.

Work with rich text fields

Some text editing fields in Commerce, for example the text fields for content-type
widgets such as the About Us Web Content widget, use a third-party editing tool,
CKEditor. These fields have their own set of keyboard shortcuts. For information, refer
to the CKEditor documentation.

30-2
31
Secure Your Service
This section describes the security features built into Commerce, including the administration
interface and the storefront. It also lists the tasks you must complete to secure the service
yourself. It is extremely important to review and follow the directions in this section before
starting to use Commerce.
In addition, it is recommended that you become familiar with the general guidelines Oracle
provides for securing all Cloud services. This information is available through the Cloud Help
Center.

Understand security features

This section describes the security features of Commerce.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Password security
Passwords for administration interface users and shoppers accessing the storefront are
implemented using techniques that meet Oracle’s software security standards. See Secure
your Commerce logins for information on changing the initial password for the administration
interface.

User authentication
Internal users who want to access the administration interface provide their login credentials
through an HTTPS request, which obtains an OAuth 2.0 bearer token. The token is then used
to verify the authenticity of the user for subsequent requests. Registered shoppers requiring
access to secure pages, such as their profile or checkout, are authenticated in the same way.
See Configure Shopper Settings for information about configuring the length of a logged-in
shopper session.
The administration interface automatically logs users out after a period of inactivity, to comply
with the Payment Card Industry Data Security Standard (PCI DSS). By default, this period is
15 minutes. You can change this value by setting the sessionTimeout parameter using the
saveAdminConfiguration endpoint in the Admin API. For example, to change the period to
30 minutes:

PUT /ccadmin/v1/merchant/adminConfiguration HTTP/1.1

Authorization: Bearer <access_token>
Content-Type: application/json

{
"sessionTimeout": 30
}

31-1
 Chapter 31
Understand security features

You can set sessionTimeout to any integer from 3 to 120. Note that this timeout period
also applies to the access token that is returned when logging into the Admin API with
login credentials. See Use the REST APIs for information about logging into the REST
APIs.

Payment gateway integrations

As explained in this guide, Commerce has built-in integrations with CyberSource and
Chase Paymentech for credit card processing. The security key and account
information required for these integrations are encrypted using a symmetric 256-bit
AES key. For more information on the secure handling of credit and debit card data,
refer to Configure Payment Processing.
Oracle Commerce integrates with PayPal Express Checkout. Calls to PayPal are not
encrypted for transmission, as the merchant ID and secret key are never exposed on
the storefront. (All calls to PayPal are made over HTTPS and performed on the server
side.) For more information, refer to Configure the PayPal integration.

Web Service APIs

Commerce includes REST web service APIs you can use to provide integrations and
extensions of the administration interface and the storefront. These APIs are
implemented using Jersey (JAX-RS) version1.14.
The APIs use the OAuth 2.0 security framework for data exchange.
Developers register their application in Commerce, which generates a JWT (JSON
Web Token) application key. If necessary, the key can be regenerated to revoke
existing access. For more information, refer to Register applications.

Customer accounts
Shoppers can choose to become registered customers by creating accounts through
your storefront. You configure the password requirements (for example, length and
case) on the Shopper Settings page in the Commerce administration interface. It is
highly recommended that you familiarize yourself with guidelines for strong passwords
and set your storefront’s requirements accordingly.
If necessary, you can revoke account access for all registered customers by expiring
all passwords. For more information, refer to Configure Shopper Settings.
Account information for registered customers is stored in a database-backed
Commerce profile repository.

Webhooks
As described in this guide, Commerce can use webhooks to send JSON notifications
to specified URLs each time an event occurs, for example, each time a shopper
completes an order. The webhook contents are signed using HMAC and hashed using
SHA256 and a secret key specific to your implementation. The key can be
regenerated if necessary. For more information, refer to Use Webhooks.

PCI DSS compliance

Not all external systems you integrate with Oracle Commerce will comply with the
Payment Card Industry Data Security Standard (PCI DSS). Oracle Commerce
provides webhooks that exclude payment details from the order data you send to

31-2
 Chapter 31
Perform security tasks

systems that do not comply with PCI DSS. For more information, refer to Understand
webhooks and PCI DSS compliance.

CORS support
For security purposes, web browsers implement the same-domain policy, which prevents
JavaScript on a page served from one domain from accessing resources on another domain.
In some cases, you may want to selectively override this policy to allow specific domains to
access data on your sites.
To make this access possible, Commerce supports CORS (cross-origin resource sharing),
which is a standard mechanism for implementing cross-domain requests. For more
information, refer to CORS support.

Perform security tasks

This section lists the tasks you must perform to harden the security of your instance of
Commerce.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Obtain an SSL certificate

The storefront uses SSL to encrypt sensitive data while it is being communicated between
the web server and the customer’s browser. To activate SSL and correctly identify your
company with your storefront, an SSL certificate is required.
You must obtain an SSL certificate for your company so it can be installed on the web server.
After the certificate is installed, the customer’s browser displays several trust indicators,
including the HTTPS URL protocol and the padlock icon, when he or she visits your store.
For more information, contact your Oracle Support representative.

Secure your Commerce logins

A username and password are required to access the Commerce administration interface.
You receive one initial username and password from Oracle as part of the process of setting
up your service. Change the password immediately by following these steps:
1. Log into the Commerce administration interface.
2. Click the Settings icon and select Access Control.
3. Click the name of the initial user.
4. Ensure the Email Address field contains a valid email address to which you have
access.
Note: If you add or change the email address, and then click Save, you may have to
refresh the Access Control page for the new value to appear.
5. Click Reset User Password.
6. The system sends an email to the specified address. Use the link contained in the email
to change the password.
All administration interface passwords automatically expire after 90 days. After this period,
users will be unable to access the service until they reset their passwords. To do so, they
should click the Can’t Sign In link on the login page and follow instructions.

31-3
 Chapter 31
Perform security tasks

If your service has been upgraded from a previous release, the 90-day period starts
after the upgrade.
User accounts are locked after six unsuccessful attempts to access the system.
Refer to Create new user profiles for instructions on how to create additional user
accounts and for information on the different access levels you can assign. It is highly
recommended that you give each user the least amount of access he or she requires.
Commerce enforces the password requirements described in Create new user
profiles, but you should ensure additional secure practices around login credentials, for
example by not emailing passwords to new users and by recommending regular
password changes.
Ensure that accounts are deactivated promptly if they are no longer needed, for
example when an employee leaves the company. See Deactivate and reactivate user
profiles.

Implement Storefront Single Sign-On

Oracle Commerce enables you to integrate customer logins on your storefront with an
external customer data store or identity management tool. For example, suppose you
have an existing informational website with a large number of customer accounts.
When you create a new Commerce site, you may want to provide existing customers
with accounts on the commerce site. . For more information, refer to Implement
storefront SSO for account-based shoppers.

31-4
A
Appendix: Layout Widgets and Elements
This section summarizes each of the widget types, accompanied by a brief outline of the
relevant page layouts, and any associated elements, that can be found within the Design
page.

This section applies to Storefront Classic only.

Account Addresses
This widget is used in account-based storefronts.

This section applies to Storefront Classic only.

It allows all contacts to view account and profile addresses. Contacts with the Administrator,
or Account Address Manager roles can create, edits, and delete account address, and
specify a default billing/shipping address for the account. It also allows contacts who have the
Profile Address Manager role to create, edit, and delete profile addresses.
In order to use this widget, a vertical tab stack must be created with the Account Addresses
widget placed on a tab. This widget is read-only unless it is being used by the Profile Address
Manager role and/or the Account Address Manager role.
It is available for the Shopper Profile layout.

Account Contacts
This widget is used in account-based storefronts.

This section applies to Storefront Classic only.

It provides the Administrator with an interface for viewing, adding, removing, and modifying
account contacts. Using this widget, the Administrator can also activate a contact as well as
assign roles to a contact.
In order to use this widget, a vertical tab stack must be created with the Account Contacts
widget placed on a tab that is accessible to contacts with the Administrator role only.
It is available for the Shopper Profile layout.

Account Details
This widget enables the shopper to enter their account details, including their name and email
address, and is used for shopper profile information in account-based storefronts.

This section applies to Storefront Classic only.

A-1
 Appendix A
Address Book

It is available for the Shopper Profile layout.

Address Book
This widget enables the shopper to enter their address details, and is used for shopper
profile information in account-based storefronts.

This section applies to Storefront Classic only.

It is available for the Shopper Profile layout.

Add Product to Wish List

This widget enables the shopper to add a product to their wish list.

This section applies to Storefront Classic only.

It is available for the Product layout.

Assets
This widget enables the shopper to see any assets that are associated with the
shopper’s account.

This section applies to Storefront Classic only.

It is available for the Assets layout.

Asset Details
This widget enables the shopper to view the details for an asset selected from the
Assets layout.

This section applies to Storefront Classic only.

It is available for the Asset Details layout.

Breadcrumb
This widget enables the shopper to see breadcrumbs showing category hierarchies for
both categories and products.

This section applies to Storefront Classic only.

Breadcrumbs help the shopper to navigate back to a category or product.

It is available for the Product, Search Results, and Collection layouts.
The following elements are available for the Breadcrumb widget:
• Breadcrumb Links

A-2
 Appendix A
Cart Shipping

• Image
• Rich text
• Text

Cart Shipping
This widget enables the shopper to enter shipping address details and select a shipping
method so they can see an estimate of shipping costs, including taxes etc.

This section applies to Storefront Classic only.

It is available for the Cart layout.

The following elements are available for the Cart Shipping widget:
• Image
• Rich Text
• Shipping Address
• Shipping Methods
• Shipping Options
• Shipping Title
• Text

Cart Summary
This widget enables the shopper to view a summary of the products added to their shopping
cart.

This section applies to Storefront Classic only.

It is available for the Checkout layout.

Category Content
This widget displays images, collection descriptions and collection long descriptions for a
selected category.

This section applies to Storefront Classic only.

It is available for the Collection layout.

Checkout Schedule Orders

This widget creates a scheduled order on a checkout page.

This section applies to Storefront Classic only.

A-3
 Appendix A
Collection

The widget identifies things such as the scheduled order name and ID, next order
date, schedule details, order contents, and so on. It is available on the Scheduled
Order Layout.
See Configure page layouts for scheduled orders for more information.

Collection
This widget displays items grouped together into a collection, for example, shoes,
furniture, clocks etc.

This section applies to Storefront Classic only.

It is available for all layouts.

Collection Navigation
This widget enables the shopper to navigate to a collection of items, and specifically
provides category navigation for larger catalogs.

This section applies to Storefront Classic only.

It is available for all layouts.

Collection Navigation Basic

This widget enables the shopper to navigate to a collection of items, and specifically
provides category navigation for smaller catalogs.

This section applies to Storefront Classic only.

It is available for all layouts.

Content Item
This widget is used to retrieve data from a content management tool.
After entering the URL and access token for the CaaS server, from where the data is
retrieved, an asset ID is used to retrieve the particular content item.
It is available for all layouts.

Customer Address
This widget enables the shopper to enter their shipping and billing addresses.

This section applies to Storefront Classic only.

It is available for the Checkout layout.

A-4
 Appendix A
Checkout Address Book

Checkout Address Book

This widget provides the shopper with the ability to look-up and select saved shipping
addresses.

This section applies to Storefront Classic only.

It is available for the Checkout layout.

Important: Account-based storefronts cannot use the Customer Address Book widget. This
widget allows shoppers to edit their billing and shipping addresses. In account-based
storefronts, shoppers require certain roles in order to manage profile and account addresses.
The Managed Account Address Book widget enforces these role requirements, so it should
be used instead of the Customer Address Book widget for the checkout flow in account-
based storefronts.
See the Create Page Layouts that Support Different Types of Shoppers chapter for more
details.

Customer Profile
This widget gives the shopper access to their personal details.

This section applies to Storefront Classic only.

It is available for the Profile layout. Note: This widget may be affected in future releases by
deprecations to default functionality.
Important: Account-based storefronts cannot use the Customer Profile widget. This widget
allows shoppers to edit their billing and shipping addresses. In account-based storefronts,
shoppers must have specific roles in order to create and edit addresses. Therefore, the
Customer Profile widget is inappropriate for account-based storefronts. Instead, for an
account-based storefront, use a Profile layout with a vertical tab stack with widgets
appropriate to account-based shoppers, including the Account Addresses widget.
See the Create Page Layouts that Support Different Types of Shoppers chapter for more
details.

CyberSource Payment Authorization

This widget provides the ability to enter form data to be used for authenticating payments.

This section applies to Storefront Classic only.

It is available for the Payer Authentication layout.

Footer
This widget provides a consistent footer throughout the web store, giving access to common
links.

A-5
 Appendix A
Guided Navigation

Generally, footers may include privacy policy details, contact information, shipping
links, sign-ups, social links and copyright information.
It is available for all layouts.

Guided Navigation
This widget allows the shopper to refine any given search, based on the search
results.

This section applies to Storefront Classic only.

Search refinements are displayed based on the entered ‘search’ term.

It is available for the following layouts:
• Collection Layout
• Search Results Layout

Gift Card
This widget enables the shopper to use a gift card as payment for their cart items.

This section applies to Storefront Classic only.

It is available for the Checkout layout.

The following elements are available for the Gift Card widget:
• Gift Card Fields
• Image
• Rich Text
• Text

Header
This widget provides a consistent header throughout the web store, giving access to
common links such as the store logo, sign-in/register links, and shopping cart access.

This section applies to Storefront Classic only.

It is available for all layouts.

The following elements are available for the Header widget:
• Cart link
• Currency
• Image
• Language
Note: You can use the Hreflang Groups endpoints in the Admin API to create
groupings of sites and languages to use in hreflang tags on your pages. If you

A-6
 Appendix A
Hero

use this feature, you will need to customize the language picker that is implemented by
the Language element. See REST API for Oracle Commerce for more information about
the Hreflang Groups endpoints.
• Links
• Login/registration
• Logo
Note: When adding your company logo, you must delete the pre-loaded logo element
and replace it with a logo image. To do so, drag the Image element to the widget row,
upload a new image of your logo, and configure the image as required.
• Rich Text
• Search
• Text
These elements are also available for the Header widget but should only be used in account-
based storefronts (see the Create Page Layouts that Support Different Types of Shoppers
chapter for more details):
• Contact Login (for Managed Accounts)
• Company Logo
• Company Name

Hero
This widget is used for displaying marketing images.

This section applies to Storefront Classic only.

It is available for all layouts.

Login/Registration Checkout
This widget enables the shopper to either log in or register their details during checkout.

This section applies to Storefront Classic only.

It is available for the Checkout layout.

Loyalty Details
This widget enables a registered shopper to view information on the status of their loyalty
program, including, points accumulated, points available for spending, points already spent,
and so on.

This section applies to Storefront Classic only.

One loyalty program is detailed per shopper, however, this can be modified to display all of a
shopper’s loyalty programs memberships. For further information, refer to Work with Loyalty
Programs.

A-7
 Appendix A
Loyalty Payment

It is available for all layouts.

Loyalty Payment
This widget informs the shopper that they have made a payment using their loyalty
points.

This section applies to Storefront Classic only.

In order to use loyalty points as a payment, the loyalty point gateway must be enabled.
Details on how to integrate with a gateway for paying with loyalty points is described in
Work with Loyalty Programs.
It is available for the Checkout layout.

Managed Account Address Book

This widget is used in account-based storefronts.

This section applies to Storefront Classic only.

This widget is used in account-based storefronts. It provides the shopper with the
ability to look up and select shipping addresses saved for the account they are
associated with; see the Create Page Layouts that Support Different Types of
Shoppers chapter for more details.
It is available for the Checkout layout.

No Search Results
This widget enables the shopper to clearly see that no search results were found.

This section applies to Storefront Classic only.

It is available for the No Search Results layout.

Notifications
This widget provides the shopper with notifications related to their actions, for
example, confirmation and validation messages.

This section applies to Storefront Classic only.

It is available for all layouts.

Order Approvals
This widget allows an approver to approve or reject an order and provide comments
when viewing an order’s details.

A-8
 Appendix A
Order Approval Settings

This section applies to Storefront Classic only.

Note that Order Approvals widget only appears in the storefront when an approver is viewing
an order’s details. Otherwise, it is hidden.
It is available for the following layouts:
• Scheduled Order Layout
• Order Details Layout

Order Approval Settings

This widget provides the delegated administrator with an interface for enabling and disabling
order approvals and setting the purchase limit.

This section applies to Storefront Classic only.

In order to use this widget, a vertical tab stack must be created with the Order Approval
Settings widget placed on a tab that is accessible to approvers only.
It is available for the Profile layout.

Order Confirmation
This widget enables the shopper to see order confirmation details upon placing an order.

This section applies to Storefront Classic only.

It is available for the Order Confirmation layout.

Order Confirmation Summary

This widget enables the shopper to see a summary of their order upon placing an order.

This section applies to Storefront Classic only.

It is available for the Order Confirmation layout.

Order Confirmation with Additional Info

This widget enables the shopper to view information related to invoice payment selection and
purchase order number(s) on the order confirmation page.

This section applies to Storefront Classic only.

It is available for the following layouts:

• Order Confirmation Layout
• Order Details Layout

A-9
 Appendix A
Order Details

Order Details
This widget provides the shopper with details related to their order including date,
status, product details etc.

This section applies to Storefront Classic only.

It is available for the Order Details layout.

The Order Details widget also enables you to choose whether or not to provide
shoppers with the ability to add a purchase list, or to cancel/return orders.
Note: For shopper-initiated cancellations/returns:
• In order to use the cancellations/returns feature, the latest version of the Order
Details widget must be utilized. This release of Oracle Commerce automatically
contains the latest version, however, if you are running an older version of
Commerce you must ensure the Order Details widget is upgraded. See Upgrade
deployed widgets for details on replacing a widget with the latest version.
• As the cancellations/returns feature is disabled by default, you must enable these
options within the Order Details widget to avail of the feature.
• Once shopper initiated returns are enabled, you will see the Return Items button
within the Order History Details widget.
• Once shopper initiated cancellations are enabled, you will see the Cancel button
within the Order History Details widget.
• Either shoppers or agents can begin the cancellation/returns process. Refer to
Cancel an order for details on agent-initiated cancellations/returns.

Order Details with Additional Info

This widget enables the shopper to view information related to invoice payment
selection and purchase order number(s) on the order details page.

This section applies to Storefront Classic only.

It is available for the Order Details layout.

Order History
This widget provides the shopper with a summary of their previous orders.

This section applies to Storefront Classic only.

If you are running more than one site, the Order History widget displays information
that is site-specific.
It is available for the following layouts:
• Shopper Profile Layout
• Order History Layout

A-10
 Appendix A
Order Summary

Order Summary
This widget enables the shopper to review their order from the cart page before proceeding to
checkout.

This section applies to Storefront Classic only.

It is available for the Cart layout.

Order Summary Checkout

This widget enables the shopper to review their order from the checkout page and then place
their order.

This section applies to Storefront Classic only.

Additionally, they may have an option to checkout with PayPal.

It is available for the Checkout layout.

Orders Pending Approval

This widget allows an approver to view a list of orders pending approval.

This section applies to Storefront Classic only.

In order to use this widget, a vertical tab stack must be created with the Orders Pending
Approval widget placed on a tab that is accessible to approvers only.
It is available for the Profile layout.

Overlayed Guided Navigation

The Guided Navigation widget allows the shopper to refine their search, based on the search
results.

This section applies to Storefront Classic only.

Search refinements are displayed based on the entered ‘search’ term.

This widget is optimized for mobile display.
It is available for the Collection, and Search Results layouts.

Page Not Found

This widget displays a message to the shopper that the page they searched for has not been
found.

This section applies to Storefront Classic only.

A-11
 Appendix A
Pay After Approval

It is available for the Error layout.

Pay After Approval

This widget is used in account-based storefronts.

This section applies to Storefront Classic only.

It provides the shopper with the ability to place an order, wait for the order to be
approved, and then make the payment once approval has been granted for that order.
It is available for the Checkout layout.

Payment Details
This widget enables the shopper to select their payment type and enter their card
payment details.

This section applies to Storefront Classic only.

It is available for the Checkout layout.

Payment Methods (Formerly Split Payments Widget)

The Payment Methods widget enables shoppers to pay for orders by choosing from a
variety of available payment methods, and is available as a component on the
Checkout layouts.

This section applies to Storefront Classic only.

It allows shoppers to choose between single or split payments, and encompasses a

range of functionality that is specific to several individual widgets in Commerce. For
example, enabling the shopper to select their payment type, enter their card payment
details, and using a gift card as a payment method. The individual widgets that
combine to form the range of functions contained in the Payment Methods widget
include:
• Split Payments
• Payment Details
• Gift Card
• Payment Gateway Options
Note: If required, you can continue to use these widgets independently.

Payment Gateway Options

This widget provides the shopper with a list of payment gateway options for checkout.

This section applies to Storefront Classic only.

It is available for the Checkout layout.

A-12
 Appendix A
Product Details

The following elements are available for the Payment Gateway Options widget:
• Cash Payment
• Image
• Rich Text
• Text

Product Details
This widget displays the details of a product to the shopper.

This section applies to Storefront Classic only.

This can include: image, description, variant detail, quantity, and stock indicator.
This widget also allows the shopper to add an item to their cart and share on social media or
email.
It is available for any layout.
The following elements are available for the Product Details widget:
• Add to Cart Button
• Add to Wish List Button
• Alternate Image Selector
• Back
• Description
• Image
• Inventory status (Refer to Customize inventory status messaging for details.)
• Long Description
• Name
• Price
• Product Image
• Product Quantity
• Rich Text
• Shipping Surcharge
• Social Sharing
• Text
• Variant options
• Volume Pricing

Product Listing
This widget displays a list of products relevant to the shopper’s navigation context.

A-13
 Appendix A
Product Recommendations

This section applies to Storefront Classic only.

When directly navigating via a collection, this widget displays products belonging to
that collection. When navigating via a search, this widget displays a list of products
matching the given search term. Each product is shown with the product image, name,
and price.
It is available for the Collection, and Search Results layouts.
You can configure a number of settings for this widget, including Display Options, and
Web Application Configuration options.
For information on how to use this widget in popup stacks, see Add Popup stacks.

Support generic sort on the product listing widget

The ProductListing widget uses productListingViewModel to fetch products,
pagination, scroll and sort. You can enable the sort to use any product property as the
sort parameter using this code in the product-listing widget:

[Link]().useGenericSort = true;

You will need to update the sort options with the required parameters, described in the
following table. For example if you want to add the sort option as displayName
property, you might use the following:

var sortOptions = [{
"id": "displayName",
"displayText": Name - Asc,
"order": [Link]("asc"),
"maintainSortOrder": true,
"serverOnly": true
}];

Parameter Description
id This must be same as the property name on
the product on which you want to sort. This
can also be a dynamic property.
displayText This is the localized value of what you want to
display in the widget.
Order Either asc for ascending sort order or desc for
descending sort order.
maintainSortOrder Set to true if you want the view models to use
the parameter set for Order. If set to false, the
order will default to asc for ascending order.
serverOnly Set to true for sorting on the server side. Set to
false to sort on client side within the available
data.

Product Recommendations
This widget enables personalized shopper product recommendations to be displayed
to the shopper.

A-14
 Appendix A
Product Social Meta Tags

This section applies to Storefront Classic only.

It is available for all layouts.

The following elements are available for the Product Recommendations widget:
• Recommendations Title
• Recommendations Carousel
• Image
• Text
• Rich Text
For information on how to use this widget, see Display product recommendations.

Product Social Meta Tags

This widget provides meta tag support for structured data markup on web pages as well as
other applications.

This section applies to Storefront Classic only.

It provides Open Graph (OG) protocol meta tags to control the content displayed when a
page is shared on Facebook. Additional meta tags are included for use with search engine
optimization ([Link], Pinterest, and Twitter). The meta tags provided in this widget are a
subset of the meta tags available. Consult your company’s development team for more
details on how to tailor this widget to your business needs.
It is available for the Product layout.

Product Quick View

This widget displays summarized details of a product to the shopper in the form of a popup
page.

This section applies to Storefront Classic only.

This can include: image, description, name, and price.

It is available for the Collection, and Search Results layouts.
For information on how to use this widget, see Add popup stacks.

Promotion
This widget enables the shopper to apply a promotional coupon to their order.

This section applies to Storefront Classic only.

It is available for the Checkout and Cart layouts.

A-15
 Appendix A
Purchase Lists

Purchase Lists
The widget displays a list of purchase lists, and allows a shopper to select a purchase
list to modify, and use a search box to search for products.

This section applies to Storefront Classic only.

It is available for the Profile layout.

Refer to Enable Purchase Lists for further details.

Purchase List Details

This widget displays details of individual purchase lists, and displays the details of an
individual purchase list.

This section applies to Storefront Classic only.

All items are selected by default for addition into the cart. A shopper can select specific
items to add to the cart or modify the quantities of the selected items. This widget also
allows a shopper to search for and select products.
The widget also allows a purchase list creator to share a purchase list. You can share
purchase lists with registered shoppers and account-based contacts.
This widget is available in the Purchase List Details layout.
Refer to Enable Purchase Lists for further details.

Quick Order
This widget enables shoppers to quickly add known items to their shopping cart by
entering a combination of product name, and/or SKU ID, either in their entirety, or part
thereof.

This section applies to Storefront Classic only.

Shoppers can also import items to a Quick Order form from a CSV file.
In order to use the Quick Order layout/widget, the following tasks must be performed:
1. Any product property that you would like a shopper to be able to search for on the
quick order page must be visible on the storefront and marked as “Allow Property
to be Searched” in the product type in the catalog. Refer to the Property types
section of this document for further information.
2. Add the properties from the previous step to the TypeAhead searchable field
ranking list, as described in the Add fields to the searchable field ranking list, and
Understand the searchable field rank sections of this document.
3. You have the option to configure the maximum number of items to add to the cart,
and the default number of rows that appear on the Quick Order widget within the
widget Settings.

A-16
 Appendix A
Quote Details

4. Place the Quick Order widget in a popup stack. Refer to the Add popup stacks section of
this document for further information.
This widget is available for all layouts.

Bulk import using CSV file

To import items using a CSV file, the shopper would click on the Import file button, browse to
a CSV file, and select it.
Each row of the import file must contain two columns:
• SKU ID (string)
• Quantity (numeric)
You can specify a maximum number of items that the shopper can import. If the number of
items in your CSV file exceeds the configured maximum, an error message will display.

Quote Details
This widget provides the shopper with the details of a quote which they have previously
requested.

This section applies to Storefront Classic only.

It is available for the Order Details layout.

Related Products
This widget provides the shopper with related product recommendations, as defined by the
merchant.

This section applies to Storefront Classic only.

Note: Only one instance of this widget should be included in the layout as multiple instances
can display redundant recommendations.
It is available for the Product layout.
The following elements are available for the Related Products widget:
• Related Products Title
• Related Products Carousel
• Image
• Rich Text
• Text

Return Items
This widget enables the shopper to initiate returns for returnable items.

This section applies to Storefront Classic only.

A-17
 Appendix A
Return Item Details

It is used when shoppers click the Return Items button whilst viewing past orders on
the Order Details widget.
It is automatically available on the Return Items layout for the latest version of
Commerce. However, if you are running an older version of Commerce, you must
ensure that you drag the Return Items widget to the Return Items layout as this layout
will appear blank in older versions. See Upgrade deployed widgets for further details
on replacing a widget with the latest version.

Return Item Details

This widget lists the details of items that have been returned by the shopper.

This section applies to Storefront Classic only.

It is available on the Order Details layout.

Request Quote
This widget enables the shopper to request a quote for their order.

This section applies to Storefront Classic only.

It is available for all layouts.

Review Order
This widget enables the shopper to review their order before placement.

This section applies to Storefront Classic only.

It is available for the Checkout layout.

Scheduled Order
This widget displays the details of a scheduled order such as the scheduled order
name and ID, next order date, schedule details, order contents, and so on.

This section applies to Storefront Classic only.

It is available on the Scheduled Order Layout. See Configure page layouts for
scheduled orders for more information.

Scheduled Order List

This widget displays a list of scheduled orders created by the current shopper.

This section applies to Storefront Classic only.

A-18
 Appendix A
Scheduled Order - Checkout

It is available on the Profile Layout. See Configure page layouts for scheduled orders for
more information.

Scheduled Order - Checkout

This widget presents UI controls to the shopper that capture the schedule information for a
scheduled order, including a name for the scheduled order, the start and end dates, the
frequency, and the option to suspend the scheduled order.

This section applies to Storefront Classic only.

It is available for the page types within the Checkout layout. See Configure page layouts for
scheduled orders for more information.

Search Results
This widget displays search results – in a similar way to the Product Listing widget.

This section applies to Storefront Classic only.

It is available for the Search Results layout.

Shopping Cart
This widget enables the shopper to view the items added to their shopping cart.

This section applies to Storefront Classic only.

The shopper can also use this widget to amend the cart details.
It is available for the Cart layout.

Split Payments
This widget enables the shopper to pay for an order using multiple payment methods.

This section applies to Storefront Classic only.

It is available for the Checkout layout.

Update Password
This widget enables the shopper to update their password by entering their current password
and then updating this to a new one, and is used in account-based storefronts

This section applies to Storefront Classic only.

It is available for the Shopper Profile layout.

A-19
 Appendix A
Web Content

Web Content
This widget allows the merchant to display HTML content.

This section applies to Storefront Classic only.

This includes About Us, Contact Us, Privacy, Returns and Shipping web content.
It is available for all layouts.
The following elements are available for the Web Content widget:
• Image
• Rich Text
• Text
Within the Settings tab of each of the Web Content instances you can access a rich
text editor from the Element Library. (If you are using Version 2 of this widget, then it
contains by default a single rich text element which is accessed upon opening the
element in the Layout tab.) This allows you to make style configurations, view source
content, and insert images via a URL.
To add an image via a URL:
1. Find and open your preferred image in the Media page.
2. Copy the image location path.
3. Open the Image Properties icon within the relevant Web Content Widget instance
Settings tab.
4. Paste the URL in the Image Info tab URL text box.
Note: When adding an image URL you must add a ‘/file’ immediately before
the file name. For example, ‘/general/[Link]’ would become ‘/file/
general/[Link]’.
5. Click OK to confirm.

Wish List Canvas

This logical widget allows a shopper to create an article page (a static text page) for
Facebook Canvas display.

This section applies to Storefront Classic only.

The associated page is shown exclusively on Facebook.

It is available in Components for use in the Wish List layout.

Wish List Content

This widget works together with the Wish List Header widget to display the appropriate
wish list to the shopper.

A-20
 Appendix A
Wish List Header

This section applies to Storefront Classic only.

In the administration interface, Layout preview, only the logged out state of this widget is
displayed, showing no content. In the Storefront preview, providing an example of when the
shopper is logged in, the contents of widget are then visible.
It is available in Components for use in the Wish List layout.

Wish List Header

This widget provides wish list management features that include the uploading of a profile
image, selecting the wish list to be displayed, and creating a wish list.

This section applies to Storefront Classic only.

In Layout preview, only the logged out state of this widget is displayed: an empty line. In
Storefront preview, when the shopper is logged in, this widget is visible. When not logged in,
this widget is not visible.
This widget works with the Wish List Content widget to display the appropriate wish list to the
shopper.
It is available in Components for use in the Wish List layout.

Wish List Invitation

This widget is a logical widget with no UI, handling the wish list acceptance flow.

This section applies to Storefront Classic only.

It creates a link to the shopper’s email client so the shopper can send an invitation to a family
member/friend to view their wish list. This widget is included by default. Nothing needs to be
configured to enable it. However, if customization is desired, make changes to the widget
through the Design page.
The wish list invite acceptance flow involves logging out the current user and triggering the
invitation modal. Once the invitee logs back in to create a new account (for new users) or
logs in as a registered shopper, the link validates the invitation token and joins the new
member to the associated wish list. The widget handles the behavior of members accessing
a wish list.
It is available in Components for use in the Wish List layout.

Wish List Notification Settings

This widget allows shoppers to opt in/opt out of their wish list email notifications.

This section applies to Storefront Classic only.

Notifications include:
• Comment and product.
• New member.

A-21
 Appendix A
Wish List Settings Header

The logged out state is shown in the preview.

It is available in Components for use in the Shopper Profile layout, the Wish List Profile
layout, found under Shopper Wish List Profile.

Wish List Settings Header

This widget displays the title and Back to My Account button for the Wish List Settings
page.

This section applies to Storefront Classic only.

It is available in Components for use in the Wish List Profile layout, found under
Shopper Wish List Profile.

Wish List Welcome

This widget allows the merchant to provide general welcome information to a shopper
about the wish list capability on their site, such as messaging to encourage wish list
creation, wish list features, and benefits of having a wish list.

This section applies to Storefront Classic only.

In the administration interface, Layout preview, only the logged out state of this widget
is displayed, showing the introductory welcome message that a non-logged-in shopper
sees when accessing a wish list, as well as log in and create an account buttons.
The Wish List Welcome and Wish List Content Header widgets are associated. The
Wish List Welcome widget displays the logged out UI. The Wish list Header and Wish
list Content widgets show the logged in UI. The Wish List Header widget determines
which wish list to show, and Wish list Content widget shows the wish list determined by
the Wish List Header widget.
It is available in Components for use in the Wish List layout.

A-22