Skip to content

PrestaShop catalog sync ​

The Humind module for PrestaShop synchronizes your catalog with Humind, sends your orders and CMS pages, and adds the Humind widgets to your storefront. Install it, connect it to your Humind account in one click, and your products, variants, prices, stock and categories flow to Humind on their own.

This page covers the module and the catalog. For the widgets, see Install on PrestaShop.

Requirements ​

  • PrestaShop 1.7.8 or later, 8.x and 9.x: the module refuses to install on an older version. PHP 7.1 or later with the curl extension.
  • A shop served over HTTPS on a public domain, for the one-click connection and the widgets.
  • A Humind account. You can create it during the connection.
  • One shop and one currency (see Limits).

Install the module ​

  1. Download the module: humind-latest.zip.
  2. In your PrestaShop back office, open Modules > Module Manager, click Upload a module and pick the zip.
  3. Click Configure on the Humind module. An employee needs the right to configure this module to open its page.

Installing the module changes nothing on your storefront until you connect it.

If a catalog was already sent through the API ​

What the module writes is kept apart from what an API key wrote before. A company with an older catalog would hold both: products and pages in double, and collections refused because their handle is already used. Ask Humind to remove the old catalog before you connect the module.

Connect to Humind ​

The module offers two ways to authorize itself against your Humind account. The one-click connection is the recommended one.

Connect in one click ​

  1. On the module configuration page, click Connect to Humind.
  2. Your browser opens Humind. Sign in, or create your account if you don't have one yet: your email address is prefilled and the company takes the name of your shop. Your address is still confirmed by email, and the connection resumes after that, even a few days later.
  3. Humind shows the shop that asks for the connection. Choose the Humind company to link it to, or create a new one, and confirm.
  4. Humind sends you back to the module configuration page, which reads Connected to followed by your company name, then shows the Your connection to Humind panel.

That is all. Behind the scenes, Humind:

  • creates a live API key labeled PrestaShop module for this shop, with the scopes the module needs, and hands it to the module once. You never see or copy it, and the module never displays it again;
  • allows the domain of your shop, so the widgets can load on it;
  • starts the first full sync and the incremental synchronization, and calls the cron and full sync URLs of the module itself: the cron every minute, the full sync every night. You have nothing to schedule and no option to tick.

Good to know:

  • The code of the connection is single use and expires after 10 minutes. If it expires, click Connect to Humind again.
  • The shop address must be public and use HTTPS. A shop on localhost or on a private address cannot be connected this way.
  • The key appears in Settings → Developer → Credentials in your dashboard like any other key, so you can see when it was last used.
  • Only an administrator of the Humind company can link a shop.
  • A shop belongs to one Humind company at a time, and a company links one shop. To move a shop, disconnect it from the first company.
  • A company that holds the orders or the catalog of a shop it connected cannot connect another one: contact Humind if the same shop moved to a new address.
  • A company already connected to Shopify cannot link a PrestaShop shop.
  • The shop address cannot carry a port.

When a firewall blocks Humind ​

During the connection, Humind reads a short proof on your shop to confirm that you control it. If a firewall or a security service such as Cloudflare blocks that call, the connection still succeeds and the synchronization works, but the domain is not allowed automatically. The module then shows a warning with an Allow my domain link to the right page of your dashboard. Humind has already opened the request for your domain there: on the allowed domains page, add the DNS TXT record it shows and verify the domain (the request stays open for 24 hours, and a DNS change can take time to propagate). Until the domain is allowed, the widgets will not load.

The same service can block the calls Humind makes to the cron URL. See the cron.

Enter an API key manually ​

If you prefer to manage the key yourself, or if your shop cannot be reached by the one-click flow:

  1. In your dashboard, open Settings → Developer → Credentials and create a key. See Authentication for the steps. Give it the scopes catalog:read, catalog:write, imports:write, knowledge:write, orders:write and customers:identity. Order tracking in the chat and signed-in customers still need the one-click connection (see below).
  2. Paste the key in the API key field under Advanced options and click Save. The key is stored in the PrestaShop configuration and is never displayed again, and Catalog changes switches on. To replace it later, use Replace the API key under Advanced options; leave the field empty to keep the saved key. Replacing a key connected in one click revokes it.
  3. Optionally fill Company ID (the 24-character identifier shown on the same dashboard page). It lets the widgets identify your company where the shop domain cannot, such as on a localhost test window. The page must still be on an allowed domain, or on localhost while a localhost test is allowed.
  4. Allow your shop domain yourself on the URL whitelist page. Humind asks you to prove that you control the domain, with a DNS TXT record.
  5. Click Sync everything again once for the first catalog, and schedule the cron URL yourself (see the cron).

Disconnect ​

The Disconnect button under Advanced options revokes the key in Humind (when the connection created it) and removes it from PrestaShop. A key you entered by hand is only forgotten by the module: revoke it in your dashboard if you no longer need it. Disconnecting also renews the feed token: whoever kept the feed URL no longer reads the catalog. Uninstalling the module does the same as Disconnect. Your products stay in Humind. Reconnect at any time with Connect to Humind: the first full sync starts again by itself.

You can also disconnect the shop from the integration card in your Humind dashboard. The module does not learn it at once: it keeps showing the connection, then warns that Humind no longer accepts its key or, once Humind stops calling the cron, that your changes no longer reach Humind. Click Disconnect in the module to reset it (its message about the key that could not be revoked is then expected).

The first full sync ​

After a one-click connection, the first full sync starts by itself. The module exports every product of the shop as NDJSON, uploads it to Humind and starts the asynchronous import. Disabled products are sent too, with the status archived, so Humind knows about them without recommending them. The export goes by slices: where a host stops long scripts, the next cron call resumes it.

The module page shows Import in progress, then Products sent and Last update, and you can leave the page in the meantime. The details are in your dashboard under Settings > Catalog > Catalog import.

With a key entered by hand, click Sync everything again once. The same button is there whenever something looks out of date: the catalog, the collections and the pages are all sent again.

A full sync re-reads the whole catalog, and Humind accepts at most 6 imports per hour per company. The cron carries the day-to-day changes, and Humind re-runs a full sync every night by itself once the shop is connected in one click.

Products gone from the shop ​

A full sync archives in Humind the products the shop no longer has, unless a product failed to export. The first import only serves as a reference. When a sync finds less than 80% of the products of the last one, nothing is archived and the module page asks: Archive them confirms, and the night sync never does it for you.

Keep the catalog fresh (cron) ​

Changes enter a queue in PrestaShop while Catalog changes is on (Advanced options > What is sent; the one-click connection switches it on): products created, updated or deleted, stock, combinations, images, brands, features, reductions and the promotions that start or end. The hooks only write to the queue: saving a product in the back office stays fast whatever the state of the network. The Cron URL shown under Advanced options > Automatic updates empties the queue.

  • Connected in one click: Humind calls the cron URL every minute. There is nothing to do.
  • API key entered by hand: call the URL every minute yourself, for example with a server cron:
bash
* * * * * curl -fsS "CRON_URL_FROM_THE_MODULE" > /dev/null

Replace CRON_URL_FROM_THE_MODULE with the exact URL displayed on the module page, which already contains your secret token. Keep it confidential, like the full sync URL.

How it behaves:

  • Each call handles at most 100 queued products, sent to Humind in batches of 20, and 20 orders.
  • A product that fails goes to the back of the queue and is retried on a later call. Failures are recorded in the PrestaShop log (Advanced Parameters > Logs). A product that kills PHP stops holding back the others: it comes back after an hour, or when it is saved again.
  • Products deleted in PrestaShop are archived in Humind by the cron.
  • The cron sends the queued orders first, then the products, the categories whenever a category or a product changes (see Collections), and the CMS pages.
  • A price rule on the whole catalog has no product to queue: it reaches Humind with the next full sync.

If the cron is not called, nothing is lost: changes wait in the queue until the next call.

Watching the cron ​

Under Advanced options, the module page shows Last run, the time of the last cron call, and the number of products and orders waiting. If the cron has not run for more than 5 minutes, a warning appears at the top of the page: changes no longer reach Humind. With a key entered by hand, schedule the cron URL. Connected in one click, it usually means that a firewall or a security service lets only browsers through and blocks the calls from Humind: allow the robot HumindBot (its user agent contains HumindBot), or add to the crontab of your server the line shown under Line for the crontab of your server, ready to copy. Until then, your changes leave when an employee who can configure the module uses the back office. After 10 failed calls in a row, your Humind dashboard also flags the shop as unreachable, or says that a firewall blocks Humind.

What is synchronized ​

Products ​

A product without a name in the default language (the empty row PrestaShop creates when you click "Add a new product") is left out until it is saved with a name.

Humind fieldSource in PrestaShop
Product external IDPrestaShop product ID
TitleProduct name
DescriptionThe short and the long description together, as plain text, with the contents of a pack
HTML descriptionLong description (HTML), otherwise the short one
URL slug and product URLLink rewrite and product page URL
CategoriesCategory names (the root and home categories are skipped)
ImagesProduct images, the cover first
BrandManufacturer
TranslationsThe same fields in every other active language
Statusarchived for a disabled product or a product a visitor cannot reach (reserved to a group of customers), unlisted when its visibility is "nowhere", active otherwise
Metafields prestashop.<feature>Product features (for example Material or Dimensions), translated per language. A feature with several values becomes a list
Metafields prestashop.*Tags, availability and delivery texts, condition, weight, shipping dimensions and unit price, contents of a pack (pack_contents), and price_hidden on a product whose price the shop hides
Complementary productsAccessories (at most 25 per product)

Variants ​

Humind fieldSource in PrestaShop
Variant external IDproduct-{id} for a product without combinations, combination-{id} otherwise
SKUCombination reference, otherwise the product reference
PriceThe price a visitor of the shop sees: default country and default currency of the shop, reductions applied, with tax unless the Visitor group displays prices without tax
Compare-at priceThe regular price, when a reduction applies
CurrencyThe default currency of the shop
StockAvailable quantity, never below 0 (a negative stock from backorders is sent as 0). A pack has the stock of its items
AvailabilityAvailable when the stock is above 0 or backorders are allowed
Options and variant titleCombination attributes (for example Color: Blue, Size: M), translated per language
ImageThe first image attached to the combination, on its own variant
Metafields prestashop.gtin and prestashop.mpnEAN-13 and MPN (the combination value, otherwise the product value)
Add to cartThe native PrestaShop add-to-cart action, so the widget adds to the real cart (see Add to cart). What PrestaShop refuses in one click goes through the product page: hidden price, catalog mode, not orderable online, minimum quantity above 1, required customization

Languages ​

Only the active languages of the shop are sent; a deactivated language is left out. Translations are keyed by base code, as the widgets ask for them: gb and us become en, tw and cn become zh, qc becomes fr, br becomes pt, mx, ag, cb, pe and ve become es, dh becomes de. Other two-letter codes are sent as they are. When two languages share a code, the default language wins, then the plain one.

At the connection and at each full sync the module also sends the list of languages. The first list of a connected shop: a company holding at most one language takes it; one holding two or more keeps them and its primary language, and the missing languages are added. After that, only a language new in the shop is added: the primary language never changes, nothing is removed, and a language you removed from Humind does not come back. A reconnection is not a first connection. With an API key pasted by hand, the list is ignored. The starting questions and the product questions are translated into the languages added, once. A language removed from the shop stays in Humind.

On a shop connected before it sells anything in Humind, when the address typed at signup is not the address of the shop, the first full sync also replaces the store description and the starting questions read on that other site by a description and questions drawn from your catalog, in the default language of the shop. Empty, they are written from the catalog too. A description or questions you have changed are left alone, as are questions switched off, tied to a knowledge entry or already translated.

Collections ​

PrestaShop categories become Humind collections, with the external ID category-{id}. Each collection carries:

  • its title, prefixed by the parent category when two categories share the same name,
  • its description and its page URL,
  • the products it contains,
  • its translations in every active language.

The technical root and home categories are not sent. A disabled category, or one a visitor cannot reach, is archived. A deleted category is archived by the cron.

A collection only holds the products Humind already knows when it receives it. The full sync starts an asynchronous import, so the module waits for the import to end and the cron then sends the collections. While some products are still missing, it sends them again 15 minutes later. The cron also sends the collections whenever a category or a product changes, at most once every 15 minutes. See Linking products by external_id.

Sync everything again sends them again with the catalog. Collections need the cron: with an API key entered by hand and no cron, they are not sent.

Orders, signed-in customers and CMS pages ​

Beyond the catalog, the module covers three more things. Orders and CMS pages are switches under Advanced options > What is sent, on by default. Signed-in customers has no switch of its own: it follows the chat widget.

  • Orders. When an order is validated, also by a payment webhook, the module reads the humind_attribution cookie that the chat widget sets on your domain and queues the order. Status changes are queued too. The cron sends them to Humind: the order, then its status, label, tracking number and tracking URL. Humind measures the sales the assistant contributed to, and flags the order lines that were added to the cart from the chat. Each order sent carries the customer identifier and email, the lines and the totals, in the currency of the shop. Orders placed before the connection are not sent in bulk: one of them is sent whole the first time its status changes. Nothing is sent during checkout itself, so the customer never waits for Humind. If Humind refuses the orders (for example a key entered by hand without the orders:write scope), they stay in the queue and the module page shows the error until the key is fixed. The shopper-facing side, order tracking in the chat, is described in Order tracking.
  • Signed-in customers. The chat widget calls the identity page of the module on your shop (index.php?fc=module&module=humind&controller=identity, or /module/humind/identity with friendly URLs). For a signed-in customer, the module obtains a short-lived identity token from Humind, server to server, and gives it to the widget, so the customer can follow their own orders in the chat without typing anything. Anonymous visitors get an empty answer, and the customer's email never goes through the browser: the token only carries their PrestaShop identifier and expires after 30 minutes. Order tracking in the chat and signed-in customers need the one-click connection: only it records your company as a PrestaShop one. With a key entered by hand, orders are still sent and attributed, but the chat does not track them.
  • CMS pages. Your CMS pages (delivery, returns, about...) become webpage entries of the Humind knowledge base, in the folder PrestaShop > Pages, with their HTML and their translations, so the assistant can answer from them. They are sent by the cron whenever a page changes, and with Sync everything again. Disabled or deleted pages are archived.

The module calls the Humind Orders API for you, with the orders:write scope.

Product feed ​

The module also exposes a token-protected CSV feed, one row per variant, for merchants who prefer Humind to pull the catalog on a schedule instead of the API synchronization. Copy the Feed URL from Advanced options into your dashboard under Settings > Catalog > Catalog import > Product feed, test it, and review the field mapping. See Product feed URL. Renew the feed token issues a new URL if the old one is exposed; update it in Humind afterwards.

Limits ​

  • One shop. The module connects the current shop only, and shows a warning when several shops are enabled: choose the shop in the selector at the top of the back office before you connect, disconnect or save a key, since a connection belongs to one shop. PrestaShop multistore is out of scope.
  • The price of the default country. Humind holds one price per variant: the one a visitor gets in the default country of the shop, with the tax of that country. Prices for other countries or for groups of customers are not synchronized.
  • One currency. Prices are sent in the default currency of the shop. Other currencies and currency conversions are not synchronized.
  • Stock per warehouse. The module sends the available quantity of the shop. Per-warehouse stock of the PrestaShop advanced stock management is not synchronized.
  • At most 250 combinations per product. Humind receives 250 of them, those for sale first, and the module page says so.
  • Theme cart counter. After an add from the chat, the widget emits the PrestaShop updateCart event. A theme whose cart counter does not listen to this event shows the old number until the next page load. The product is in the cart.

Troubleshooting ​

  • The connection fails. Check that the shop address is public and in HTTPS, then click Connect to Humind again. The code of a connection lasts 10 minutes and works once. If the shop is already connected to another company, disconnect it there first.
  • There is no Connect to Humind button. The shop already has a key, entered by hand. To move to the one-click connection, click Disconnect under Advanced options, then Connect to Humind.
  • The module says that Humind could not confirm your domain. A firewall or a security service blocks the proof call, or the domain is linked to another Humind company. The synchronization works; finish the domain request that Humind opened for you on the allowed domains page (DNS TXT record).
  • A product appears twice, or a sync fails on a collection whose handle is already used. An older catalog sent through the API is still in Humind. See above.
  • A price differs from the Humind price. Humind receives the price of the default country, reductions applied, in the default currency of the shop. Check tax rules, the Visitor group and specific prices in PrestaShop.
  • Changes in PrestaShop do not reach Humind. Check Last run and the Catalog changes switch under Advanced options. If the cron has not run for more than 5 minutes, allow the robot HumindBot in your firewall or add the crontab line shown by the module. Failed products are listed in the PrestaShop log.
  • The module says that the last full sync stopped before the end. It is probably a time or memory limit of your server. Try Sync everything again; if it stops again, your host can raise these limits.
  • Orders do not arrive. The module page shows the refusal from Humind when the key lacks a scope. Click Disconnect, then Connect to Humind, or use Replace the API key with a key that has the missing scope. If you entered the key by hand, switch off Orders and CMS pages when the key lacks their scopes.
  • The widget does not show. See Verify.

Next ​

Released under the proprietary Humind license.