HubSpot + Akeneo integration

Akeneo is where a brand or distributor turns supplier spreadsheets into products ready for every channel. Families define the attributes, product models carry what variants share, and completeness scores say when a product is ready for a given channel and locale. Commerce sites and marketplaces read that data. The sales team, working from HubSpot all day, usually does not.

So the product library in HubSpot is a second catalogue somebody maintains by hand. It lags the enriched one, carries names marketing retired months ago, and misses new variants entirely. B2B sellers quote from it anyway, and customers compare the quote with the website. Marketing notices the drift first, because it approved the names, and sales notices it last, when a buyer asks why the quote and the product page disagree.

The fix is small once it is framed properly. Akeneo stays the only place product data is edited, HubSpot receives the fields a seller needs for the channel sales actually uses, and nothing flows back. Because Akeneo scores completeness per channel, the sync can send only products that are complete for the sales channel, which keeps half-finished items off quotes and gives the product team one more reason to finish them.

Products become HubSpot products. Variant products carry their product model’s code as a property, so sellers can find every size of one design, and the model itself never becomes a HubSpot product because Akeneo never sells it on its own. An asset from the Asset Manager supplies each product’s image URL.

The key is the product UUID, held in a custom unique property. Akeneo recommends its UUID endpoint because a UUID never changes, even when an SKU is modified, and because some products have no traditional identifier at all. The SKU still travels, in hs_sku, because it is what sellers search for.

Prices come from Akeneo price attributes, which hold one amount per currency, and map onto the price fields HubSpot keeps for each currency the account uses. Values are read for one channel and locale agreed in discovery, because Akeneo stores values per channel and locale while HubSpot holds one value per property.

The dependable path is a polling watermark sync. A connection in Akeneo provides a client id and secret for an API user, and the service exchanges them for a token that lasts an hour, refreshing it as it goes. Each run reads the products endpoint with the updated filter after the stored watermark, in UTC on SaaS, using search-after paging at 100 products a page.

The service maps each product for the agreed channel and locale, upserts HubSpot products in batches keyed on the UUID, and moves the watermark only after the batch commits. A weekly run compares every UUID with HubSpot to catch the deletions the filter cannot see, and a replay endpoint re-reads any window on request.

On SaaS editions, an Event Platform subscription posts product events to an HTTPS endpoint that queues them and answers within five seconds. Delivery is at least once and unordered, so an event only tells the service which UUID to read next.

The deciding factor here is the edition more than the budget. On Akeneo’s SaaS editions the Event Platform supplies events, and the build pairs them with a scheduled read. On the Community Edition or the Enterprise Edition hosted as PaaS there are no events to subscribe to, so the scheduled read carries everything, which is simpler and still fresh enough for a product library.

An iPaaS suits a small catalogue that changes rarely. The ceiling it meets is concurrency: Akeneo allows four concurrent calls per connection and ten per instance, shared with every other connection, and a per-task tool reloading a large catalogue spends both time and money. A custom API integration controls both.

1. Scope. We choose the families, attributes, channel and locale that sales needs, confirm the edition, and find out where images are hosted.
2. Architect. We fix the UUID as the key, the watermark and page size, the currency mapping and the completeness rule for what reaches HubSpot.
3. Build. The service is written against a sandbox or a Community Edition copy and a HubSpot sandbox, on a dedicated Akeneo connection.
4. Validate. We load the catalogue, compare UUID counts with HubSpot, and check prices and images with the product owner.
5. Operate. We watch 429s and event failures, run the weekly deletion pass, and re-check the mapping when a family changes.