Cortex and Core Terminology Differences
Cortex and the core platform (Core engine, Web Applications, and Commerce Manager) use different terminology to describe similar e-commerce concepts. This document is a partial list of some of these differing terminologies.
Why use different terminology?
Cortex is designed to live not just on top of our e-commerce platform, but also on top of other e-commerce platforms and even other applications. So the terminology used to describe Cortex concepts is chosen to be in line with our API multipurpose software model.
For example, the term SKU (Stock Keeping Unit) describes a physical product in a store. When you use Cortex for a store that doesn’t have physical goods and has entitlements, use the term item to describe SKUs and products to encompass both physical and non physical goods.
The same goes for SKU Options, which are known as Item Definition Options in Cortex. The term Item Definitions doesn’t have a good mapping to other known e-commerce terminology. Think of Item Definitions as descriptions of the Item, which include:
- Name
- Details
- Components
- Options
- Images
Terminologies
The terminologies used by Cortex, don’t always map one to one with core platform terminologies. They usually share similar concepts, but are not always exact match.
The table below lists some of the key e-commerce terms that are different in Cortex and the core platform.
| Cortex API Terms | Similar Core Term | Notes |
|---|---|---|
| Item | SKU, product | An item is basically an I.D. that is used to track your purchases. This I.D. is unique to a specific configuration of a product. |
| Item Definition Options | SKU option | A variant of the item/sku. For example, an red iPod and an green iPod would each have a different Item Definition Option and a SKU option. |
| Orders | Cart-Order | An order tracks the information required from the customer to make a purchase, like the customer’s payment details, shipping address, and items to purchase. |
| purchases | Order | Record of your completed transaction. |
| Shipping Options | Shipping Service Level | The shipping service to use for the shippable good the customer is purchasing. |
| Navigations | Catalog Categories | Navigations are directly mapped to catalog categories. |
| components | bundle | - |
| profiles | Accounts | These are basically the same thing. |
Items Explained
Initially, the terminology and concepts for Items, Item Definitions, components, and Item Definition Options may be confusing for client app developers. Particularly for developers who are more familiar with Elastic Path Commerce Engine terminology and concepts. Keep in mind Cortex is designed to live in front of different applications, not just Elastic Path Commerce Engine, so the terminologies and concepts describing the API are designed to fit this multipurpose model. For more information, see Why Use These Terminologies section.
Below are some of the key terminologies and concepts used in Cortex.
Items
An Item is a purchasable good, like a T-Shirt, movie, song, or entitlement. In other words, anything that can be purchased through Cortex is an item. The Items resource’s responsibility is to handle the item’s purchasability, which is why availabilities, prices, and the addtocart form are on the item.
Item Definitions
An Item Definition is a description of an Item. The item’s name, media assets (pictures of the item), options, and details (characteristics of the item) are all part of the item definition.The Item Definitions resource’s responsibility is to handle the merchandising data that describes the item.
Item Definition Options
An Item Definition Option is a variant of the item. For example, the item may be get a movie, Finding Nemo, which has an Item Definition Option called Video Quality. Video Quality has two choices: Standard Definition or High Definition. The two different resolutions, Standard Definition and High Definition, are the item option’s choices, while the Video Quality is the Item Definition Option. The Item Definition Options’ resource is responsible for listing the options available for an item, while the itemselections resource is responsible for the Selectors used to select choices for the option.
Item Components
Items can have components, which are other items. For example, the item may be a Sci Fi Classics Movie Package and movies in the package are item components. You can have nested item components inside other item components. Alternatively, the Sci Fi Classics Movie Package item could have the movie Forbidden Planet as a component and it could have the Star Wars Trilogy package as a component. The Star War Trilogy package then has 3 other components, each of which are components. In most cases, components can be purchased separately by following the component’s standaloneitem link. For more information, Read Item Definition Component in the Resource Reference Guide.
How do I access Items, Item Definitions, and Item Definition Options?
Start with the item. Most of the API Entry Points, searches, and navigations point to items. From items, you access the Item Definitions and Item Definition Options. This may seem like a long path to take in order to get the Item Definitions and the Item Definition Options, but by using Zoom, see Zoom, you can get all this data with one request.
Why Separate Items, Item Definitions, and Item Definition Options?
Three words: REST Level 3. Cortex is a REST Level 3 API, which means API responsibilities are broken up into individual units called resources. Each resource is designed to be responsible for the smallest amount of tasks as possible, which is why we separated Items, Item Definitions, and Item Definition Options into different resources. Compartmentalizing responsibilities into different resources provides a lot of flexibility for switching resources out, adding new ones, and even removing existing ones.
Aren’t Item Definition Options actually separate Items?
Yes you’re right, technically they are. The Finding Nemo Standard Definition and High Definition movie are two separate discs, they even have different packaging, but Cortex organizes them under one item with different item options. This is similar to how the core platform’s multi-SKU products are organized in the store.