MarketplaceHub Docs Docs

WooCommerce

How WooCommerce connects through our plugin: key approval, publishing by SKU, price and stock that keep a sale, and orders read on notice.

WooCommerce® is a source, a publishing target and an order channel, and the source of truth for price and stock while the merchant has Real-time stock sync on. It connects through our plugin, MarketplaceHub for WooCommerce, which does only what WooCommerce's REST API cannot. Every product, price, stock and order call goes to the store's own REST API (wc/v3). One store per account.

Authorization

The merchant types the store's address. MarketplaceHub checks the store and the plugin there, then sends the browser to WooCommerce's own key approval page. The merchant approves as an administrator or a shop manager, and WooCommerce makes a read and write REST key for MarketplaceHub. The key does not expire: it ends when it is deleted in the store, which Disconnect does, on the plugin's page or in MarketplaceHub. The key is stored encrypted, and the merchant's WordPress password is never seen.

The store needs WordPress 7.0, WooCommerce 11.0 and PHP 7.4 or later, HTTPS, and permalinks other than Plain.

The plugin

  • Change notices. When a product, a category or an order changes, the plugin sends a signed notice that carries ids only, never product or buyer data. MarketplaceHub then reads the change through the REST API. Notices run on WordPress's scheduled tasks, which run when the store has visitors, so every kind of notice has a regular check behind it.
  • Shipments. Core WooCommerce has no shipment record, so the plugin keeps the shipments MarketplaceHub sends with the order and shows them to the buyer.
  • The copy guard. A site at another address than the one it was connected at sends nothing until the merchant says whether the store moved or the site is a copy.

Importing from WooCommerce

Every product except those in the trash is read, one row per SKU: a simple product's, or each variation's. A product or variation without a SKU of its own is skipped and counted, because every later write finds a product by its SKU. Grouped and external products are skipped. The price is regular_price; a running sale is kept as a separate value and never imported as the price. Stock comes in only where WooCommerce counts it for that SKU.

Publishing

  • No second copies. The store is searched by SKU before every create. A product already there is linked and edited, and a create is never resent.
  • Categories. Each product goes under one of the store's own categories, or the default category the merchant chooses in Store defaults. WooCommerce asks for no category details, so nothing beyond the shared fields is required.
  • Pictures. WooCommerce downloads every picture link into the media library, so a picture already sent to the store goes by its attachment id instead.
  • Brands are matched by name and never created.
  • Removing makes a draft. Nothing is deleted, and a product in the trash is never restored by a publish.

Price and stock

  • To the store, while MarketplaceHub leads: regular_price only, never sale_price, and stock as a whole number with manage_stock on. WooCommerce ends a sale whose price is not below the regular price, so a price at or below a set sale price is held and the merchant is told.
  • From the store, with Real-time stock sync on: a product's notice is read about 30 seconds later, so a burst of saves is read once, and a daily read lists every product and variation changed since the last one. Only regular_price and counted stock are read.

Orders

Orders are read by the time they changed: every 10 minutes, slowing to once an hour when it is quiet, and at once after an order notice. The first read covers 7 days. An order waiting for payment is stored once it is paid.

  • Ship. The shipment goes to the plugin with a key, so sending it again changes nothing. When every line has shipped, the order is set to completed.
  • Cancel takes whole orders only, before anything has shipped, and WooCommerce puts its stock back. A part-order cancel is refused before anything is recorded: see the orders API.
  • Refund goes through the payment method when it supports refunds. Otherwise WooCommerce only records it and the merchant pays the buyer back. The order's refunds are read before every refund, so one is never sent twice, and a refund made in WooCommerce comes in with the order.
  • No fulfilment channel is reported: the merchant ships every order.

Rate limits and firewalls

Every store is a different server, so calls are paced at two a second per store, and a 429 or 503 with Retry-After holds the store. A security plugin or firewall that blocks MarketplaceHub is reported to the merchant, and the store stays connected. Calls carry the user agent MarketplaceHub/1.0 (+https://marketplacehub.com).

WooCommerce and its associated designs are trademarks of Automattic Inc.