Here you will find the main structure of how the catalogs are organized in our systems. It's important to know that you will have categories, stores, products, and catalogs that are related as follow:

493493

As you can see above, the "Catalog" is the interacts with the e-commerce experience. The attributes of "Stores", "Categories" and "Products" are displayed in the e-commerce associated to a Catalog. That means that the customer

Next, you will find the explanation of each resources ("Catalog", "Products", "Stores" and "Categories") with their attributes and what they are used for. Also, you will see an explanation of promotions associated a one catalog and how to create them.

NOTES:
If you want to see the technical documentation click here.
if you are an old customer and want to know the improvements of Catalog V2 in contrast to Catalog V1, click here.

INITIAL CONSIDERATIONS

  • The product that you want to have diplayed in the e-commerce must have a "Catalog" record.

  • The static information of a product is stores in a "Product" record.

  • A Catalog record will alway have a "Product", "Store" and at least one "Category" associated.

STORES

The first thing that you need to do, is create the Stores. Each "Store" record represents one store where the customer can purchase in e-commerce.

All The attributes that a "Store" returns when GET API is consumed, are described below:

ITEMTYPEDESCRIPTION
idStringUnique store identifier. It's used to identify the store in the database and is the key that relates a Store with a Catalog.
nameStringName of store. The name will appear in the e-commerce when the user selects "Pick up in store" method.
storeReferenceStringStore identifier for the customer
latitudeDoubleCoordinate
longitudeDoubleCoordinate
phoneStringPhone number of the store
addressStringAddress of the store. The address will appear in the e-commerce when the user selects "Pick up in store" method.
addressTwoStringAuxiliary address of the store
countryStringCountry where the store is located. The country will appear in the e-commerce when the user selects "Pick up in store" method.
selfStringPath to get the store through API

How to create?:

For the first iteration, you are be able to create a Store through one ticket about "Configuration of ecommerce - Operation: create new Store".

CATEGORIES

In e-commerce, products are organized by categories and subcategories to simulate an online experience comparable to a physical store.

The attributes that one "Category" must have are described below:

ITEMTYPEDESCRIPTION
idStringUnique category identifier
nameStringName of the category
typeStringAlways “CATEGORY”.
categoryReferenceStringCategory identifier for the customer
parentIdStringid of the parent category in the category tree. The parentId of the main categories must have the id of the "DEPARTMENT" category.
slugStringIt’s the last part of the URL after the last backslash when the user is viewing the category in the e-commerce
boostInt32It organizes the display order of the categories in one level of e-commerce (according to the category tree). To lower “boost”, greater prioritizing of the category (displayed from top to bottom)
isAvailableHomeBooleanIf this attribute is “TRUE”, the category is displayed in the home of e-commerce, otherwise no. Only apply for categories level 1
selfStringPath to get the category through API

Category Tree:

The categories are divided into levels that you can hierarchize with "parentId" attribute.

When you create an e-commerce, the system automatically creates one category type "DEPARTMENT", which will be the root level of the Category Tree. The "DEPARTMENT" category is not a real category but It's necessary for creating the categories that will be displayed in the e-commerce. All others categories will be sublevels of the "DEPARMENT" category and must be type "CATEGORY".

Bellow, you will see an example of an e-commerce with five categories: 3 categories level 1 (the parent category must be the "DEPARMENT" category) and two level 2 under "Dairy Products" category:

757757

Considerations:

  • For a better user experience, It’s recommended that products be in the lower levels, because the higher levels show the products contained in their sublevels.

  • You can have the same product in different categories, such as “Dutch cheese” in the example above.

It's important to know that the categories contain "CATALOGS" and not "PRODUCTS", so you can have products within different categories per store. this is possible because each catalog record must have a store and category (one or more) associated with it. If you want to have one special category only in one store, the only thing that you need to do is create catalogs with the category and that Store.

How to create?:

For the first iteration, you are be able to create a Categories through one ticket about "Configuration of ecommerce - > Catalog: update categories".

PRODUCTS

A “Product” record stores the intrinsic attributes of a product, that usually don’t change and is used to feed the catalog records.

All the attributes that a "Product" must have are described below:

ITEMTYPEDESCRIPTION
idStringUnique product identifier
skuStringProduct identifier for the customer
eanArray of StringsType of barcode that encodes a product number. One product could have multiples ean.
nameStringname of the product
unitStringUnit of measure or packaging form of the product. Example: "Pack" or "Kg"
photosUrlArray of StringsURLs that contain product photos
NutritionalDetailsStringURL that contain a photo that is show at the end of all photos
clickMultiplierInt32Number of products to add to the shopping cart when a user clicks on add product ("+" symbol)
subUnitStringSubunit of measure or a single unit of the product. Examples: “Bottle” or “gr”
boostInt32It organizes the display order of the products in the same category (according to the category tree). To lower “boost”, greater prioritizing of the product (displayed from top to bottom)
descriptionStringDescription of the product
slugStringIt’s the last part of the URL after the last backslash when the user is viewing the product on the e-commerce
VariantsArray of Objectspossibility of having variants of a product (In progress)
FormatsArray of Objectspossibility of having formats presentation of a product (In progress)
selfStringPath to get the product through API

How to create?:

For the first iteration, you are be able to create a products through API with a POST request for Products(see the endpoint).

CATALOG

A “Catalog” record stores the attributes that frequently change such as “price” and “stock”, and will always have a “Product”, “Store” and at least one "Category" associated that feed the Catalog displayed in the e-commerce.

It's important to know, a “Product” stores the intrinsic attributes of a product that are equal for all stores that carry that product, and “Catalog” stores the attributes that change among stores.

All the attributes that a "Catalog" must have are described below:

ITEMTYPEDESCRIPTION
idStringUnique catalog identifier
productIdStringUnique product identifier
storeIdStringUnique store identifier
priceInt32Price of the product in one store
stockInt32Stock of the product in one store
categoriesArray of Stringlist of categories where the product can be found in one store.
maxQtyInt32Maximum quantity of units of a product in one store that the user can add to the shopping cart
minQtyInt32Minimum quantity of units of a product in one store that the user can add to the shopping cart
isActiveBooleanIf the “active” attribute is “TRUE”, the category is displayed in the e-commerce, if it’s “FALSE” the category isn´t displayed
selfStringPath to get the catalog through API
securityStockInt32Minimum number of units to have the product available in one store
locationStringLocation of the product. It could be as specific as you want, for example, warehouse, hallway, or shelf
PromotionArray of ObjectsPromotions associated with the product (see promotion section)

How to create?:

For the first iteration, you are be able to create a catalog through API with a POST request for Catalogs (see the endpoint).

PROMOTIONS

The promotions are associated with one "Catalog" record. All the attributes that a "Promotion" must have are described below:

ITEMTYPEDESCRIPTION
TypeStringType of promotion. Only "specialPrice", "stepped" and "nx$"
DescriptionStringDescription of the promotion
startDateTimeStringDate when the promotion begins in the e-commerce. (specialPrice don`t use this field)
endDateTimeStringDate when the promotion ends in the e-commerce (specialPrice don`t use this field)
isActiveBooleanIf this attribute is “TRUE” and is in range of dates, the promotion is displayed in the product in the store, otherwise no (specialPrice don`t use this field)
conditionsArray of ObjectsConditions of the promotion (see conditions)

Condition attribute:

The conditions contain an array of objects and each object has only two attributes: “qty” and “price”. The way to use the “qty” and “price” attributes depend on the type of promotion.

  • SpecialPrice : the condition only has one object. The “price” attribute is the applicable price for the product just until the specified quantity (“qty” attribute). The user will only be able to purchase until the quantity specified in the promotion, the e-commerce will not allow the user to add more than this quantity.

  • nx$ : the condition only has one object. The “qty” attribute is the number of units that the user must buy to access the price specified in the promotion (“price” attribute). The special price is only applicable for the quantity specified, if the user adds or removes one or more units, the promotion will no longer valid.

  • stepped : the condition may have one or more. The “qty” attribute is the minimum order in one range to access the price specified (“price” attribute). For example, if the condition has two ranges: 1[qty: 4, price:30] and 2[qty:10, price: 26]. Between 1 and 3 units, the unit price is the original price, between 4 and 9 the unit price would be 30, and between 10 or more the unit price would be 26.

How to create?:

For the first iteration, you are be able to create a promotion through API with a POST request for Promotions (see the endpoint).


What’s Next