↑↓ selectEnter openEsc close

    1. Elbuz
    2. Websites and CMS

    How to import a catalog from WooCommerce: store URL and REST API keys

    23 min readUpdated

    The Elbuz WooCommerce integration pulls your store's catalog and orders via the REST API, without files, into the base catalog next to your other channels.

    When you need this:

    • Your catalog is already on a WordPress site: products, variations, categories, brands, photos and SEO texts arrive in the cards.
    • Prices and stock come from supplier price lists: Elbuz calculates them, a separate template exports them.
    • The site isn't your only channel: edit a product in one place, and changes go out to marketplaces.
    • Site orders go into one queue: each becomes a “Customer order” document.

    Where to start: create a REST API key in WooCommerce.

    What the WooCommerce connection can do

    What you need from WooCommerce: the URL and a key pair

    WooCommerce has no developer app or link code. You need all three values:

    • Store URL: the full of the site, for example https://store.com. It must use https.
    • Consumer key: the access key, starts with ck_.
    • Consumer secret: the secret, starts with cs_.

    Where to get the keys: step by step

    WhereWhat to do
    WordPressSettings → Permalinks: nothing needs changing, any mode works, including “Plain”
    WooCommerceWooCommerce → Settings → Advanced → → “Add key”
    Same placeFill in the description, choose the user the key will act as, and the permissions
    ElbuzImport window → your “WooCommerce” template → “Connection” card → the URL, Consumer key and Consumer secret fields

    Once the key is created, WooCommerce shows the consumer key and consumer secret. Copy both: the secret is shown only once. A lost key can't be recovered: you create a new one and revoke the old one.

    Read is enough to pull the catalog. Read/Write is for orders and for sending prices and stock back to the site; grant it right away so you don't have to reissue the key later. Create a separate WordPress user for the integration: you'll see who accessed the store, and access is easy to revoke.

    If WordPress uses the “Plain” permalink mode, the store's regular REST API address (/wp-json/wc/v3/…) doesn't respond. Elbuz detects this on its own: it retries the request through the fallback address ?rest_route=/wc/v3/… and uses it for the rest of the run.

    Official WooCommerce guide: WooCommerce REST API. It also covers managing and revoking keys.

    How to connect

    1. Create a template of type “WooCommerce” and enter the URL, consumer key and consumer secret in the “Connection” card.
    2. Click “Check connection”: it tells you whether the site accepts your keys before the first import.
    3. In the “Select data to import” card, turn on “Products” and, if needed, “Photo” and “Orders”, then save and run.

    What goes into the card

    WooCommerce dataElbuz card field
    product nameName (for a variation: “Name — S / Black”)
    descriptionFull description
    short descriptionShort description
    product brandManufacturer
    skuSKU
    / from custom fieldsBarcode (digits only)
    regular_price / sale_pricePrice (the sale price takes priority)
    regular_price when there's a saleOld price
    stock_quantity or stock statusStock
    publish statusCard active status (a draft arrives disabled)
    product tagsTags
    category treeCategory, with the full path
    slugSEO URL (friendly URL)
    weightWeight
    SEO title and description (Yoast / Rank Math)Meta title and meta description
    regular product attributesSpecifications
    variation attributesVariant options
    product gallery + variation photoImages, when the “Photo” checkbox is on
    product and variation IDsSite link keys
    • Price: the sale price becomes the card price and the regular price the “old price”, so the discount shows as on the storefront.
    • Stock: with stock management on, the exact quantity carries over; without it, WooCommerce knows only “in stock / out of stock”, and the card gets 1 or 0.
    • Barcode: WooCommerce has no GTIN field, so Elbuz looks for it in popular plugins' custom fields and keeps only the digits.
    • : the product page title and description from Yoast SEO or Rank Math move into the card.

    Categories, brands and variations

    Categories arrive with the full path: Elbuz reads the store's category tree separately, so the base catalog repeats the site's structure. The brand becomes the manufacturer.

    Variations (sizes, colors, configurations) arrive as separate cards named like “Product name — S / Black”, each with its own price, stock and SKU; variations of one product are linked into a family. Variation axes (Size, Color) become options, regular attributes become specifications.

    Whose price stays in the card

    The price is written in a fixed order:

    1. The run writes the price from the site.
    2. When all pages are collected, the base catalog markup runs on newly created cards: it calculates the price from the purchase price, only where the purchase price is above zero. WooCommerce doesn't provide a purchase price, so a new card keeps the site price. This step skips existing cards.
    3. Last, the run recalculates fields by formulas: the “Updating values based on formulas” line. Only formulas set to apply on import run; a formula that calculates the price has the final say.

    “Fixed Price” and “Do not update” protect the card from both the markup and the import writing the price. The difference: “Fixed Price” locks only the prices, “Do not update” locks the whole card.

    Category of a new card and the manufacturer

    A new card's category is found in three steps: your category with the same full path → a category with the same name anywhere in the tree (from leaf to root) → a whole new branch. So duplicates like “Laptops (2)” don't appear while the names match.

    The diagram applies only to new cards: the run doesn't change the main category of an existing card. The bottom branch explains why a partial name match doesn't create a new branch
    NoYesYesNoYesNoNew card from the siteDoes the product on the sitehave a category?Service category “Products -woocommerce”;a new one is disabled and excludedfrom exportsOf the product's categories, thedeepest is taken;the path is built from the store's treeIs there your categorywith the same full path?The card goes into itIs there a category named like thelast linkor one of the links above it?The card goes into the nearest onefound by nameThe whole branch of the path iscreated,the card goes into the last link
    • Action or result
    • Decision: the path depends on the answer

    Products without a category go into the service category “Products - woocommerce”, which is disabled and excluded from exports. Move cards out freely: the run keeps an existing card's main category, and moving doesn't change issued documents. You can't delete the category itself while it has products: they'd go with it (service categories).

    The manufacturer is the WooCommerce product brand; with no brands, the field stays empty. A new brand is added to the directory automatically. Rename brands in WooCommerce: a brand renamed in Elbuz gets created again under the old name.

    What a repeat run does with your edits

    Every run is a full mirror of the site's catalog: the run goes through all product pages, so edits made in Elbuz last only until the next update, with no warning. There's no “changed only” mode for the catalog.

    • Overwritten from the site: name, full and short description, price, old price, quantity and stock status, SKU, barcode, weight, manufacturer, tags, SEO title and description, active status.
    • Empty doesn't erase: an empty field or zero from the site keeps the previous value. When a sale ends, the card's “Old price” keeps its former value. Only quantity and active status get overwritten with zero or empty. Stock status follows quantity: above zero is “In stock”, zero is “Out of stock”.
    • Not touched on an existing card: photos (the gallery is uploaded only on creation), specifications (new attributes aren't added), the place in the category tree, the purchase price.

    To lock the whole card, use the “Do not update” switch in the product (also the “Do not update (flag)” column in the “Products” window, set right in the grid). For just the price and old price, use “Fixed Price”. More: how to lock your own value.

    Import protection toggle group in the product card
    1Do not update
    1. Do not update — the toggle that protects the whole product from being changed by import.

    The card is matched by name, not by the product ID on the site (that's stored only for exporting back).

    Renamed on the site: the run adds a second card, and the old one keeps old numbers. Renamed in Elbuz: the card is found, and the site name returns. For a variation, the full name with the “Name — S / Black” label is compared, so renaming a size or color also creates a new card.

    The top fork is the name: it decides whether your card is updated or a new one appears next to it. The left branch shows why you turn on the “Photo” checkbox before the first run
    NoYesNoYesYesNoA product or variationarrived in the runIs there a card with the same name?For a variation, together with the “S /Black” labelNew card: fields from the site,specifications and variation optionsIs “Photo” on?The product gallery and variationphotoare uploaded to the cardCard without photos:they won't arrive laterIs “Do not update”on in the card?The card stays unchangedName, descriptions, quantity, stockstatusand active status come from the sitePhotos, specifications and maincategoryare not touched
    • Action or result
    • Decision: the path depends on the answer

    A product disappeared from the site or became a draft

    What happened on the siteWhat happens to the card in Elbuz
    The product was deletedStays as it was: with the last price and stock, enabled, with no log line. Remove it manually, or it goes into exports
    The product is a draft, private or in the trashThe next run disables the card; it's enabled only in the publish status
    The product was published againThe card is enabled

    WooCommerce has no “delete what's missing from the source” checkbox. The general rule: a product disappeared from the source.

    If you clear “Active” manually while the product is published on the site, the next run enables the card again. Only the “Do not update” flag keeps it disabled. Clearing active status deletes nothing, but a disabled card doesn't go into exports: a new export template takes only active products by default.

    How to receive WooCommerce orders

    The same connection also pulls orders, with a Read/Write key and the “Orders” checkbox on. If you only want products, leave it off.

    An order lands as an unposted “Customer order” document: stock and reservations don't change until the document is posted. WooCommerce specifics:

    • Document status: from the order state (pending, processing, on-hold, completed, cancelled, refunded, failed) via the status mapping in the template card. An unmapped state gets the first status in the directory, “New”.
    • Payment flag: from the payment date: if there's a date, paid goes into the mapping, if not, unpaid.
    • Shipping service: from the order's first shipping line, together with its name on the site.
    • An order line looks for the card by variation ID, or by product ID if there's no variation. So import the catalog first or in the same run.

    The first run pulls all orders in any state; later runs pull those changed after the date of the last imported one (in GMT, as WooCommerce returns it) and update existing documents. No duplicates: a document is matched by order ID together with the source code. The log shows an “Orders received:” line. General mechanics: importing orders.

    Scheduled updates

    Once the connection is checked, schedule the template with the task settings button in the form: prices and stock will update and new products will be added. A separate WooCommerce template in the “Data export” window, with its own schedule, sends prices and stock back to the site (export templates).

    Each page leaves a line in the log, “WooCommerce: catalog page 3, products received: 300”, and at the end, “WooCommerce: catalog loaded, products: N”. More on the log: how to check that the import went through.

    How much one run pulls

    There's no limit on the number of products. Batch sizes are fixed:

    WhatBatch
    Products100 per page, the WooCommerce maximum
    Variations100 per page, a separate request for each product with variations
    Categories100 per page; the tree is read once at the start of the run
    Orders100 per page
    Writing to the catalogbatches of 500 items

    A store with variations makes more requests to the site than the same store with simple products, so it takes longer; that's not a hang. You can close the window: the log lives in the Operations Center. The duration is shown in the “Time spent” column and in “Run history”.

    Scenarios

    All the checkboxes below are in the “Select data to import” card, except in the last scenario, where the flag is set in the product itself.

    Select data to import card with Products, Photo and Orders checkboxes
    1Products
    2Photo
    3Orders
    1. Products — import the product catalog.
    2. Photo — import product photos.
    3. Orders — import orders.

    Pull the site's catalog and leave orders on the site

    What to turn on. “Products”; “Photo” if you need images. “Orders” stays off.

    What you get. A simple product becomes a card, a product with variations becomes a family of cards. The category arrives with the full path, the brand becomes the manufacturer, and the run doesn't touch orders. There's no purchase price: WooCommerce doesn't provide it.

    Photos from the site: decide before the first run

    What to turn on. “Photo”, before the template's first run.

    What you get. Each new card gets the product gallery, and a variation card gets the variation's own photo first, then the gallery without repeats. If you turn the checkbox on after the first run, only new cards get photos.

    See how the catalog lands on the first pages

    What to click. Run the template and, once “WooCommerce: catalog page…” lines appear in the log, click “Stop” in the Operations Center.

    What you get. The run finishes the current page (up to 100 products), writes what it collected, applies the markup to new cards and closes with the line “WooCommerce: catalog loaded, products: N”. Products with the lowest site IDs come first. What's written stays in the cards; the next full run finds them by name, without duplicates.

    Receive site orders in Elbuz

    What to turn on. “Orders” together with “Products” or after the catalog is imported; if both are on, the catalog goes first.

    What you get. Each order becomes a “Customer order” document; later runs pick up changed orders and update them without a second document (orders).

    Edit a card in Elbuz so the run doesn't overwrite it

    What to turn on. “Do not update” in the product card, “Import protection” group.

    What you get. The run finds the card but changes none of its fields, stock status or specifications; changes from the site won't reach it until you clear the flag. The flag doesn't prevent a second card after the product is renamed on the site.

    What to do when WooCommerce won't import

    What the log says and what to do about it
    What you seeWhyWhat to do
    “WooCommerce: provide the store URL and API keys (consumer key/secret)” One of the three connection fields is empty; the run didn't even contact the site Fill in all three fields in the “Connection” card (what you need)
    “WooCommerce: API error -” followed by text from the store The site refused: the keys are wrong or copied with spaces, the URL isn't https or has an extra path, permissions are insufficient, or the store didn't respond Click “Check connection”: it uses the same keys and shows the refusal right away (where to get the keys)
    The keys are definitely correct, but the connection check returns an error The REST API is disabled, or the hosting or a security plugin blocks external requests Enable the REST API and allow external requests to the site
    “WooCommerce: catalog loaded, products: 0” The site responded but returned no products: the catalog is empty or the key has limited access Check the key's permissions in WooCommerce and that “Products” is on in the template
    The catalog has two identical products with different names A product or variation was renamed on the site, and the run created a new card Delete the old card (if the run did the wrong thing)

    If the run broke off

    Products go into the catalog in batches of 500, so after a break part of them are already updated and the rest still have old data. Rerunning is safe: cards are found by name, with no duplicates in either the catalog or orders, and the next successful run completes the final markup. General mechanics: if the run broke off.

    The program handles “too many requests”, “service unavailable” and protection pages itself: up to four retries, pausing as the site asks (max 30 s) or 2, 4, 6 and 8 s. It waits 180 s for a response and 30 s for a connection. After that, the run stops with the red line “WooCommerce: API error -”.

    The page loop has three exits: pages run out, “Stop” is clicked, or the site responds with an error. Only in the last case is there no final markup step
    NoYesNo, errorYesYesNoWooCommerce template runwith the “Products” checkboxAre the store URL,consumer key and consumer secretfilled in?Red line “provide the store URL andAPI keys”;the run doesn't contact the siteThe store's category treeis read onceRequest a page of products,up to 100Did the site return the page?Red line “WooCommerce: API error-”;the run breaks off without the finalstepProduct with variations: a separatevariations request,each variation becomes its own cardEvery 500 itemsare written to the catalogAre there more pagesand “Stop” not clicked?The rest of the batch is written,new cards get the markupLine “WooCommerce: catalogloaded, products: N”
    • Action or result
    • Decision: the path depends on the answer

    If the run did the wrong thing

    Cards created by this connection can be filtered in the “Products” window by the “Source - name” and “Source - Code” (woocommerce) columns and deleted in bulk; that's also how you clean up duplicates after a rename. Look for overwritten cards by “Date updated” (if you imported the wrong thing).

    Elbuz has no way to roll back an import in bulk. But the run mirrors the site, so you fix the data on the WooCommerce side and run the import again. The previous price is visible in the “Product price history” block if price history storage is on.

    FAQ

    Which permissions should the key have: Read or Read/Write?

    Read is enough for the catalog. For orders and for sending prices and stock back to the site, use Read/Write (where to get the keys).

    I lost the consumer secret. Where can I see it?

    Nowhere: WooCommerce shows the secret only once. Create a new key, enter it in the template, and revoke the old one.

    Will a repeat run overwrite my edits in the card?

    Yes: the run brings back the name, descriptions, price, stock, brand and active status from the site with no warning. It doesn't touch photos, specifications or the category of an existing card. To lock them, use “Do not update” or “Fixed Price” (repeat run).

    Why don't the cards have a purchase price?

    WooCommerce doesn't store it. The purchase price comes into the card from a supplier price list, and markup rules are calculated from it (whose price stays).

    I added a photo on the site. Why didn't it appear in the card?

    Photos and specifications are uploaded only when the card is created; the run doesn't update them on an existing card (repeat run).

    Can I delete the “Products - woocommerce” category?

    Only when it's empty: deleting a category removes all products for which it's the main category. First move the cards to your own categories. The next run recreates the service category as soon as a product without a category arrives (category and manufacturer).

    How do I bring the catalog into the system so that stock and prices are then updated on the site?

    With two templates on one Read/Write key: the WooCommerce template in “Data import” pulls the catalog, and a separate WooCommerce template in “Data export”, with its own schedule, updates prices and stock on the site.

    Where to find it and who has access

    Menu
    Directories → Operations → Data import
    Template
    new template → type “WooCommerce”; one template = one site
    Access right
    the “Import” window in “Group permissions”
    Prepare
    the site URL with https, a consumer key and a consumer secret
    WooCommerce API connection form with store address, Consumer key and Consumer secret fields and the Test connection button
    1Store address
    2Consumer key
    3Consumer secret
    4Test connection
    1. Store address — the URL of your WooCommerce site.
    2. Consumer key — the ck_... key from WooCommerce REST API settings.
    3. Consumer secret — the cs_... secret that goes with the key.
    4. Test connection — checks the connection before the import.

    How import templates work in general: data import overview.

    Related topics

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free