Skip to main content
All CollectionsWhere to Buy
Importing retailers into MetaLocator for product monitoring
Importing retailers into MetaLocator for product monitoring
Bryan Nye avatar
Written by Bryan Nye
Updated over a week ago

Importing and adding retailers into MetaLocator is one of the first steps in monitoring price data for your Where to Buy solutions.  Understanding which retailers pose the best strategic decision is covered here.  This article covers the mechanics of requesting a retailer for addition to your account.

Retail partners can be added one by one, or in bulk.  Regardless of the import method, they will be on-boarded by the MetaLocator Data Team according to your stated requirements. Retailers carry certain status codes to indicate their progress through our on-boarding pipeline. They are as follows:

  • Pending: Request has been submitted and is pending assignment and setup.

  • In-progress: Request has been assigned to a technician and setup is in progress.

  • Failed: The requested retailer can not be on-boarded as provided. This often indicates a technical or legal issue preventing the data team from moving forward.

  • Complete: Retailer setup is complete. This retailer can be published and displayed in the Where to Buy Interface.

Monitoring this status can be performed in the Control Panel under Retailers in the main navigation.

  • *name:  The name of the retailer.  The name should be in the language of the locale designated if applicable.

  • *locale: The locale of the retailer.  If the retailer applies to multiple locales, the retailer should repeat once for each applicable locale.

  • *searchurl: The link to the retailer Web site.  MetaLocator staff will later change this to the url used for searching the retailer Web site.

Fields after this point are commonly configured by MetaLocator staff during the on-boarding process.

  • searchurl: The search URL should contain a %s which serves as a placeholder for the Search Term, GroupID or GroupSearchTerm fields.  The search term is used in the global search and is set in the retailer configuration.  Any other % symbols in the URL should be replaced with "%%" so the replacement functions properly.  If the retailer supports a search parameter such as manufacturer or brand this should be included to ensure the results presented are only for the customer desired brand.

  • affiliatedeeplink:  This is the format for generating deep links to affiliate-encoded product pages.  The search URL should contain a %s which serves as a placeholder for the retailer product URL.  Any other % symbols in the URL should be replaced with "%%" so the replacement functions properly.

  • *searchterm: Usually the brand name to insert in the search URL when clicking a non-product or group-specific referral link.  This is normally the same for all retailers, but can vary for retailers that require a specific keyphrase to trigger the expected results.  This term is also passed to spiders for use during the initial data load.

  • published: A 1 or 0 indicating the retailers published status.  The published state will not be respected until the retailer status is complete.

  • logo: The image URL of the retailer logo.  Should be at least 500px wide and a 24-bit transparent background PNG.

  • affiliateusername:  The username to login to the affiliate program.

  • affiliatepassword:  The password to login to the affiliate program (stored encrypted).

  • affiliatelogin: The url to the affiliate program control panel.

  • urlappend: A tracking code to append to the Buy Now and searchurl links for this retailer.  This is optional and can be used to append any referral code or UTM parameter to the outgoing link.

  • ordering:  The numeric sort ordering of the retailer when displaying in the front-end Where to Buy tool.

  • touexception: A written exception from the retailer that allows for the use of their data in the context of a Where to Buy tool.

  • partnertype: The type of partner, [retailer|provider]

  • endpoint: The data API endpoint.  This endpoint should return data in JSON format for most API handlers.  For ScrapingHub, the format is as follows:
    The Project, Spider and Job numbers will change based on the customer configuration.

  • Spider Name: This should be the exact MetaLocator-provided name of the ScrapingHub spider.  

  • filetype:  The import engine plugin used to consume data from the API endpoing

  • type: [api|scrape] Indicates the type of data source.

  • inventory: The retailer supports location-specific inventory tracking

  • onlineonly: The retailer has no brick and mortar stores and sells products online only.

  • Allow Redirect: When set, the system will use a redirect to send the user to the affiliate program link.   Some affiliate programs do not allow redirects and in those cases this should be disabled.

  • Show Prices: Some affiliate programs do not allow display of the price under certain conditions.  Clearing this checkbox will disable the price display in all cases for this retailer.  The Where To Buy interface will instead display "Click to view price".

  • MarketPlace: Indications this retailer is a marketplace.  Marketplaces may sell the same product from multiple sellers. 

  • displaylink: When provided, the system will use this content for the innertext of the anchor tag used to display a text-based Where to Buy link.

*Indicates a required field.

Configuring Retailers Manually

MetaLocator offers a bulk import for retailers and a method to add retailers one by one.  To add retailers manually,

  1. Click Retailers on the main navigation on the left

  2. Click New in the upper right

  3. Complete the Retailer field by entering the retailer's common brand name.

  4. In the Search URL, enter the link from the retailer's Web site after performing a brand search. (See above for details)

  5. Enter the locale code by choosing from the drop-down list.  This should designate the locale for which these products should be presented.  To enter a retailer for multiple locales, enter them once for each applicable locale

  6. Upload a logo if available

  7. In general, leave the fields at their default values, unless otherwise specified. Review the field specifications above for details.

  8. The API endpoint will commonly be a Scrapinghub Storage API endpoint. E.g. This value can be obtained from the MetaLocator help desk.

  9. The Spider Name should correspond to the exact spider name in Scrapinghub, This value can be obtained from the MetaLocator help desk, e.g. en-US-sitename.

  10. Search Term. This is the default search term, commonly a brand name to use when crawling the site.

  11. Search Key List. No longer used.

  12. Response Rate Warning Threshold: This threshold tells MetaLocator what an appropriate ratio of item requests to received items is for this retailer.

  13. Error Warning Threshold: This threshold tells MetaLocator what an appropriate error rate is for this retailer. Some retailer Websites are inacccessible more often than others.

  14. Store Locator URL: This can be used to display a link to the retailer store locator in the Interface.

  15. Online Only? Is this retailer available for Buy-Online only, v.s. also buy in-store.

  16. Allow Redirect? Some affiliate program terms prohibit redirection from the Where To Buy to the retailer. Disable this to link directly to the retailer. This can prevent click attribution if disabled.

  17. Show Prices? This option prevents the display of price data for all products regardless of the underlying data.

  18. Marketplace? Indicates that this retailer is a marketplace, and multiple offers from the same retailer and product may be presented. (E.g. Amazon).

  19. Auto Unpublish? This option allows the product offboarding procedure to automatically unpublish matched products from this retailer that are detected as stagnant. Stagnant refers to products for which a price update can no longer be obtained after the number of attempts set in Maximum Number of Unanswered Update Requests Before Offboarding?

  20. Auto Hide Based On Stock Status? This option permits the public interface to automatically hide products from this retailer that are out-of-stock. This prevents the offer from being included in the data feed. The template may still include logic that hides a product based on stock status. The retailer, pricebot and/or API must support stock notifications.

Importing Retailers in Bulk

  1. Click Retailers on the main navigation on the left

  2. Click Import in the upper right

  3. Provide a CSV import file according to the template provided.

Once a retailer is properly configured, click "ReCrawl" to import the data as shown below:

This will crawl the provided API Endpoint and assimilate the products found.  This will also trigger another crawl of the retailer Website.  The results of that triggered crawl will be assimilated on the next scheduled update.  

Once crawled, the system will automatically trigger an AutoMatch procedure.  AutoMatch relies on keys being present on both the monitored product record and the retailer Web site.  Any overlap will cause an AutoMatch.  Similarly, keys found in the product name will also trigger a match.

If no matches are found, products must be manually matched.  

Did this answer your question?