MarketplaceHub Docs Docs

BigCommerce

How BigCommerce connects through our app: one token per store, publishing by SKU, stock at one location, sales channels and orders.

BigCommerce 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 the MarketplaceHub app, which the merchant installs in the BigCommerce control panel. Products go through BigCommerce's Catalog API (v3) and orders through its Orders API (v2). One store per account.

Authorization

The merchant installs the app from Connect marketplace in MarketplaceHub, or from Apps in the BigCommerce control panel, and approves the access BigCommerce shows. The install finishes in a new MarketplaceHub tab, where the merchant signs in or creates an account: the store is connected to that account. The link to that tab works once, for 24 hours.

BigCommerce gives MarketplaceHub one token per store. It does not expire: it ends when the app is uninstalled, and an uninstall also disconnects the store. Disconnect in MarketplaceHub forgets the token but cannot uninstall the app. The token is stored encrypted, and the merchant's BigCommerce password is never seen. The app asks for products, inventory, store locations and store information, orders, transactions (for refunds), and channel settings and channel listings (for sales channels).

Webhooks

  • MarketplaceHub keeps one webhook per topic: the app uninstall, categories, products, SKUs, orders and shipments. BigCommerce does not sign webhooks, so each one carries a secret header made for that store, and a webhook without it is refused.
  • BigCommerce turns a webhook off after 48 hours of failures, or after 90 days with no events. The daily check turns it back on.

Importing from BigCommerce

Every product is read, one row per variant SKU. A variant without a SKU is skipped and counted, because every later write finds a product by its SKU, and a SKU seen twice is read once. A product with more than one variant becomes a group on the options that differ. The price is price, never the sale price, and cost is not read. Stock comes from the inventory location chosen in Store defaults, and only where the store tracks it. Hidden products are imported and marked hidden. The store's own categories are kept, so a product published back to the same store keeps them.

Publishing

  • No second copies. Before every create, the store is searched by the product's SKUs, then by its variants' SKUs. A product already there is linked and edited. BigCommerce has no idempotency key, so a create is never resent: a lost answer is found by the next search.
  • Categories. Each product goes in the categories picked for it from the store's own tree, or the default category chosen in Store defaults. BigCommerce has no shared taxonomy, so every product uses one common product type.
  • Nothing guessed. A missing title, price, weight in a unit the store uses, category or variant SKU holds the product and names the gap. A product takes up to 600 variants and 1,000 pictures, each picture at most 8 MB.
  • Brands are matched by name and never created. Cost is never sent.
  • Removing hides the product (is_visible: false). Nothing is deleted, so the product keeps its orders, reviews and URL.

Price and stock

  • To the store, while MarketplaceHub leads: a price only when it differs, on the product or on each variant, never 0 and never the sale price. Stock is always sent, as a whole number at the Store defaults location, because BigCommerce's stock reads can lag behind its writes. A product that tracks no stock gets none, and the merchant is told.
  • From the store, with Real-time stock sync on: a product or SKU webhook is read about 30 seconds later, so a burst of saves is read once. The stock read is the stock on hand at the Store defaults location.

Sales channels

Each marketplace the merchant sells on through MarketplaceHub shows in the store's Channel Manager as its own sales channel, named MarketplaceHub-<Marketplace>. A product MarketplaceHub holds on the store that is also listed on that marketplace is listed on the channel, with the state of the marketplace listing.

With Copy my marketplace orders into this store on in Store defaults (off by default), each marketplace order is also made in the store, on its marketplace's channel, with the buyer's name and shipping address only and no stock moved. The order pull leaves those orders out, so a sale is never counted twice.

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 or shipment webhook. The first read covers 7 days. Statuses are mapped by status_id, never by name. An order waiting for payment is stored once it is paid.

  • Ship makes one shipment per address, tracking number and carrier. The order is read first, and units BigCommerce already shows as shipped are not sent again. BigCommerce emails the buyer when the store sends order status emails.
  • Cancel takes whole orders only, before anything has shipped, and moves no money. A part-order cancel is refused before anything is recorded: see the orders API.
  • Refund asks BigCommerce for a refund quote first, then refunds through an online payment method when there is one. Otherwise BigCommerce only records it and the merchant pays the buyer back. Store credit is never used. The order's refunds are read before every refund, so one is never sent twice, and a refund made in BigCommerce comes in with the order.
  • No fulfilment channel is reported: the merchant ships every order.

Rate limits

A store has one request allowance, shared by every app on it. MarketplaceHub uses at most half of it, and when an answer says a tenth or less is left, the store is held until the allowance resets.

Uninstall and buyer data

48 hours after the app is uninstalled, the buyer names and addresses that only that store's orders use are erased. The orders stay.