Knowledge BaseAPI ReferenceAPI Status

Magento 2 Extension

Suggest Edits

Users Guide for Topsort Magento 2 extension

👍

Easy Integration

If your marketplace is built on Magento 2, you're in luck because our integration with Magento via the plugin is really easy.

System Requirements

Supported Magento versions: v2.3.5-v.2.4.3

Installation

Magento extension needs to be installed via composer. The installation might be done following the step below.

1. Add repository information into composer.json file of the Magento 2 instance:

🚧

Note: Topsort/php-sdk repository is required only if v1 of composer is used (relevant for Magento versions below 2.3.7).*

Optional. Add the topsort/sdk repository to your composer file:

{
  "repositories": {
        "topsort-sdk": {
        "type": "vcs",
        "url": "[email protected]:Topsort/php-sdk.git"
      }
  }
}

2. Install the composer package:

composer require topsort/module-topsort-integration-magento2

3. Finish the installation by running the standard Magento command:

bin/magento setup:upgrade

Configuration

Catalog Service API
Catalog Service APIs will allow Topsort service to fetch products, categories and vendors data from your Magento instance.

Setting up Vendors
By default, Magento does not have a vendor attribute. You may use the default product attribute manufacturer or create your own attribute.

Option 1. Using the existing “manufacturer” attribute.

This can be done by navigating to “Product Attributes” page (Menu → Stores → Attributes → Product),
then search for the manufacturer attribute code.
By filling in the attribute options you can define what vendors products can be assigned to each vendor.

Option 2. Adding a new “vendor” product attribute.
By using the standard Magento functionality, we can configure a new vendor product attribute.
This can be done by clicking on “Add New Attribute” under the “Product Attributes” page (Menu → Stores → Attributes → Product).

Similar to the configuration or manufacturer attribute, the new attribute
should be configured as a “Drop-down” list. By configuring the attribute options
you will provide the list of Vendors that will later be shared with the Topsort API.

📘

Please, note that once the list of options is defined and your vendors already got their products and started using the system, you should not remove them from the list of vendors (the option associated with the vendor should not be removed).

Setting up Brands
Topsort Brands are configured in a very similar way to Topsort Vendors. Please, see the previous section of the documentation to understand, how to configure them. In the simplest setup the same attribute might be representing both: vendors and brands.

Activating the Catalog Service API
The Catalog Service API can be activated and configured in Magento configuration section: (Stores → Configuration → Topsort → Catalog Service APIs)

  • Enable catalog service APIs: once the setup is ready, set this value to “Yes” in order to open access to catalog service APIs of your Magento instance.
  • Access Token: Please, contact Topsort Inc in order to obtain a secure Access Token that you may paste into this field.
  • Topsort Vendors Attribute Code: This property is defining the product attribute code used to identify Topsort Vendors
  • Topsort Brands Attribute Code: This property is defining the product attribute code used to identify Topsort Vendors

Configuration for Sponsored Products
The behavior of sponsored products can be configured in Magento configuration under Store → Configuration → Topsort → Sponsored Products.

The “API” section includes the properties that need to be configured in order to establish the connection with Topsort API:

  • Topsort API Enabled: this option needs to be set to “Yes” in order to enable the usage of Tosport API.
  • Topsort API Key: API key required to authenticate with Topsort API.
  • Topsort API URL: The base URL for the Topsort API endpoints
  • Currency sub-unit multiplier: The multiplier used to convert the amount expressed in currency sub-units into its main unit (e.g. is 100 for US Dollar since 1 Dollar has 100 Cents).

The next two sections are “Catalog” and “Search Results”. These sections configure the rendering of sponsored products on the Magento pages:

  • Enabled sponsored products in catalog/search: set to Yes in order to start showing the sponsored products.
  • Amount of sponsored products to render: specifies the maximum amount of sponsored products that might be displayed on the page.
  • Add sponsored products if amount of products greater than: you may avoid displaying sponsored products if the catalog or search result pages have too few items on it.
  • Sponsored product label text: The text for the label that will be displayed on top of sponsored products in the list of products.

Limitations

After installation of the extension, the full-page cache on category pages will be disabled. This is required in order to show promoted products on category pages.
Promoted products will increase the number of products displayed on the first page in the product lists: in search results and on the catalog pages.

Updated 10 months ago