# Install SparkLayer on WooCommerce

URL: https://docs.sparklayer.io/help/platforms/woocommerce/install
Applies to: WooCommerce

Install the SparkLayer plugin on WooCommerce: connect your store with REST API keys, assign B2B roles, add the widgets, then set up prices and test an order.

> **Quick summary**
>
> - Install the SparkLayer plugin on your WordPress site, register with SparkLayer, then connect your store with WooCommerce REST API keys. WooCommerce support is in early access, and needs WooCommerce 9+, WordPress 6+ and PHP 8.2+.
> - A customer becomes a B2B customer when their WordPress user has a `SparkLayer B2B` role, such as **SparkLayer B2B: Base**.
> - On a block theme, the widgets are added for you. On other themes, they go in your theme files: our team can add them free of charge, or your developer can.
> - You manage SparkLayer in the SparkLayer Dashboard at app.sparklayer.io. You set B2B prices and ordering rules at **Pricing > Price lists** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/lists)), or **SparkLayer Wholesale > Pricing > Price lists** in the Shopify app and **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app.

Setting up SparkLayer on WooCommerce:

1. **Before you start**: Versions, HTTPS, SKUs, payments and shipping
2. **Install**: Add the plugin and register with SparkLayer
3. **Connect**: REST API keys, then B2B roles for customers
4. **Widgets**: Automatic on block themes; otherwise add to your theme
5. **Next steps**: Prices, customer group rules, a test order, launch

New to SparkLayer? [How SparkLayer works](https://docs.sparklayer.io/help/get-started/how-sparklayer-works.md) explains the basics, and [Storefront widgets](https://docs.sparklayer.io/help/storefront/interfaces.md) shows what the widgets do.

> **Do you need a developer?**
>
> Usually not. You can install the plugin, connect your store and set up customers yourself, in WordPress and the SparkLayer Dashboard. On a block theme, the widgets are added for you. On other themes, adding them means editing theme files: our team can do it free of charge, or your developer can. Sections that need a developer are marked "for your developer".

## Before you start

Check these in your WordPress admin before you install. It's also worth reading [WooCommerce limitations](https://docs.sparklayer.io/help/platforms/woocommerce/limitations.md).

- **WooCommerce 9 or later, on WordPress 6 or later, with PHP 8.2 or later.** [WooCommerce](https://woocommerce.com/) must already be installed on your WordPress site.
- **HTTPS turned on** for your store. The plugin only works over HTTPS.
- **A permalink setting other than Plain** in WordPress, at **Settings > Permalinks**, so the plugin can connect to WordPress and WooCommerce.
- **A unique SKU on every product**, because SparkLayer stores B2B prices by SKU. See [Add SKUs to your products](#add-skus-to-your-products).
- **A payment method.** On a test store, turn on an example payment method in **WooCommerce > Settings > Payments**.
- **Shipping rules** set up in **WooCommerce > Settings > Shipping**, or in SparkLayer's own [shipping](https://docs.sparklayer.io/help/ordering/shipping-rules.md), so orders can be placed.

Once SparkLayer is running, you'll mostly use three areas of WordPress: **Products** for products and SKUs, **Users** for B2B customers, and **Orders** for B2B orders.

### Add SKUs to your products

1. In WordPress, go to **Products** and edit a product.
2. For a simple product, enter the **SKU** under **Product data > Inventory**.
3. For a variable product, open **Product data > Variations** and enter a different **SKU** for each variation.
4. Update the product.

## Install SparkLayer

Upload the SparkLayer plugin to your WordPress site, then create your SparkLayer account.

1. Ask [our support team](https://docs.sparklayer.io/help/support.md) for the SparkLayer plugin for WooCommerce. They send you the plugin's .zip file.
2. Upload and install the plugin on your WordPress site, as you would any plugin you upload yourself. See WordPress's guide to [installing a plugin](https://wordpress.com/support/plugins/install-a-plugin/).
3. [Register for SparkLayer](https://app.sparklayer.io/register) to create your SparkLayer account.

## Connect your store

Connect SparkLayer to WooCommerce with a REST API key: a key and secret, created in WooCommerce, that let SparkLayer read and update your store. You don't need to write any code to create one. If you get stuck, [our support team](https://docs.sparklayer.io/help/support.md) can help.

1. In the SparkLayer Dashboard, go to **Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app. Under **Your platform**, select **WooCommerce (early access)**.
2. Enter your store URL: the address of the site you're installing SparkLayer on, such as `www.mystore.com`.
3. In WordPress, go to **WooCommerce > Settings > Advanced > REST API** and click **Add key**.
4. Give the key a description you'll recognise, such as **SparkLayer API**, set **Permissions** to **Read/Write**, and click **Generate API key**.
5. Copy the **Consumer key** and **Consumer secret** that WooCommerce shows. WooCommerce only shows them once, so keep the page open until you've pasted them.
6. Back in the SparkLayer Dashboard, paste them into **WooCommerce API Key** and **WooCommerce API Secret**, then click **Save**.
7. Wait a few seconds while SparkLayer connects to your store and sets up the plugin.

Your store is now connected, and SparkLayer starts syncing your products. The plugin's settings are in WordPress at **WooCommerce > Settings > Integrations > SparkLayer B2B**. Next, give your B2B customers a role.

### Give customers a B2B role

SparkLayer only syncs WordPress users with a role that starts with `SparkLayer B2B`. Each SparkLayer customer group has its own role. For the base customer group, it's **SparkLayer B2B: Base**.

1. In WordPress, go to **Users**. Click **Add User**, or edit an existing customer.
2. Make sure the customer has a complete address, with every address field filled in. Keep a note of their email address: they sign in with it.
3. Set **Role** to the SparkLayer role for the customer's group, such as **SparkLayer B2B: Base** or **SparkLayer B2B: VIP Group**. 
4. Save the user.

When the customer signs in, they get the rules of that [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md). If you create another customer group in SparkLayer, update the role on the customers who belong to it.

### Check a customer has synced

1. In the SparkLayer Dashboard, go to **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app.
2. Search for the customer by name or email. If they're listed, they've synced.
3. Click **View** to check their details. Under **Identifiers**, the **Platform ID** is their WordPress user ID: for example, `3` in `?user_id=3` at the end of the user's page URL in WordPress.

If some customers couldn't sync, a banner at the top of **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app says so: click **Show errors** to see who and why. See [Product and customer sync](https://docs.sparklayer.io/help/integrations/data-sync.md) for more.

## Add the widgets

If your theme supports blocks, the plugin adds the SparkLayer widgets (the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md)) to your store automatically. To check, sign in to your store as a B2B customer and open a product page. You should see your B2B prices.

If the widgets don't appear, or you'd rather place them yourself, they need adding to your theme files. You don't have to edit any code yourself. Choose one option:

| Option | How |
| --- | --- |
| **Ask us to add them** | Our team adds them free of charge. Go to **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app and click **Request installation**. See [Request free installation](https://docs.sparklayer.io/help/support.md#request-free-installation). |
| **Ask your developer** | Pass them the steps below. |

### Add the widgets to your theme (for your developer)

These steps edit your theme's code. Pass them to your developer.

**Step 1.** **Check the Core Script**

The [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting) turns SparkLayer on in your store. The plugin adds it to your pages automatically, as long as your theme calls `wp_head()` in the `<head>` section of its template. To pin a Core Script version, use **Version for this store** at **Storefront > Widgets > Core script version** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets > Core script version** in the Shopify app.

**Step 2.** **Add the product detail interface**

The [product detail interface](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) shows a B2B customer their prices and a way to order on each product page. Add this snippet to your product page template:

```javascript
<spark-pdp parent-id="<?php echo absint( $product->get_id() ); ?>"></spark-pdp>
```

Where it goes depends on your theme. Look for files such as `woocommerce/single-product/add-to-cart/variable.php` and `woocommerce/single-product/add-to-cart/simple.php`.

**Step 3.** **Check the product card interface**

The [product card interface](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) shows B2B prices on collection pages. It should be added automatically. If it isn't, add this snippet to the template that renders products on your collection pages:

```javascript
<spark-product-card parent-id="<?php echo absint( $product->get_id() ); ?>"></spark-product-card>
```

**Step 4.** **Hide retail elements from B2B customers**

If you're adding SparkLayer to an existing store, hide anything B2B customers shouldn't see, such as retail prices, quantity selectors, product options and buy buttons. Add `data-spark="b2c-only"` to each of those elements in your templates, or list them in **CSS Hidden Selectors** (see the next step). See the [frontend integration guide](https://docs.sparklayer.io/developers/frontend.md).

**Step 5.** **Add your CSS (optional)**

In WordPress, go to **WooCommerce > Settings > Integrations > SparkLayer B2B** and use these settings. The CSS you add here only loads when a B2B customer signs in.

| Setting | What it does |
| --- | --- |
| **CSS Overrides** | Changes SparkLayer's default styling, such as colours and fonts, with CSS variables like `--spark-primary-color: #000000;`. Start from the [recommended starting CSS](https://docs.sparklayer.io/help/storefront/customising-design.md#recommended-starting-css), without its `<style>` tags. |
| **CSS Hidden Selectors** | A comma-separated list of CSS selectors, such as `.my-class, #my-id`, for elements to hide while a B2B customer is signed in, such as a retail banner. |

See [Customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md).

When you've finished, check your setup against the [frontend integration guide](https://docs.sparklayer.io/developers/frontend.md). See [Storefront](https://docs.sparklayer.io/help/storefront.md) for the other settings you can turn on.

## Next steps

Once your customers are syncing and the widgets are in place, set up your prices and rules in the SparkLayer Dashboard.

1. **Create a price list.** Go to **Pricing > Price lists** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/lists)), or **SparkLayer Wholesale > Pricing > Price lists** in the Shopify app and click **Create price list**. An automatic price list applies a discount to your WooCommerce price or your RRP price. A manual one uses prices you upload by CSV, including quantity pricing. See [Managing pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md).
2. **Set up your customer groups.** Go to **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app. Use the base customer group, or click **Create customer group** for customers who need different rules. Choose each group's price lists, payment methods and order limits. You can manage a group's rules once at least one customer has its role. See [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md).
3. **Place a test order.** Sign in to your store as a customer with a SparkLayer B2B role and check your prices. Place a test order with each payment method you offer. See [How B2B orders arrive in WooCommerce](#how-b2b-orders-arrive-in-woocommerce).
4. **Invite your customers.** Work through the steps at **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app, then let customers know, for example with a newsletter. The [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md) has example messages.

These steps match [Get started on other platforms](https://docs.sparklayer.io/help/get-started.md#other-platforms). When you're ready to go live, work through the launch checklist:

- [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md): Test your setup, invite your first customers and go live
- [Price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md): Create a price list for each pricing tier you offer
- [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md): Choose each group's price lists, payment methods and order rules

## How B2B orders arrive in WooCommerce

Every order goes to **WooCommerce > Orders**. Its status depends on the [payment method](https://docs.sparklayer.io/help/ordering/payment-methods.md) the customer chose:

| Payment method | What the customer does | Order status in WooCommerce |
| --- | --- | --- |
| **Pay on Account** | Checks out without entering payment details. | **Pending payment**. Mark it as paid once you've received payment. |
| **Pay by Invoice** | Checks out without entering payment details. | **Pending payment**. Mark it as paid once you've received payment. |
| **Pay Online by Card** | Goes to the WooCommerce checkout and pays straight away, with any payment method you've set up (such as card or PayPal). | **Completed**, if your store is set up for this. Ready to fulfil. |

In customer groups, **Pay Online by Card** is called **Card at checkout**, **Pay by Invoice** is **Pay by invoice** and **Pay on Account** is **Payment on account**. For offline payment methods, take payment in your WooCommerce admin or offline, for example by bank transfer.

Each order also has a **SparkLayer Order Information** section, which shows the payment method the customer used.

## More settings on WooCommerce

### Stock levels

SparkLayer can show [stock levels](https://docs.sparklayer.io/help/storefront/stock-display.md) in several ways. To show stock numbers, such as 100, turn on **Manage stock** in **WooCommerce > Settings > Products > Inventory**. To show stock on product cards too, use the settings in **WooCommerce > Settings > Integrations > SparkLayer B2B**.

### Pre-orders

SparkLayer supports pre-orders (also called back orders). When a product is on pre-order, B2B customers see a pre-order message on the product page and can still buy it. See [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md#allow-pre-orders-and-back-orders).

### Tax

SparkLayer uses the tax rules you've set up in WooCommerce. See WooCommerce's guide to [setting up taxes](https://woocommerce.com/document/setting-up-taxes-in-woocommerce/).

### SparkLayer shipping

By default, B2B orders use your WooCommerce shipping methods. To use SparkLayer's own [shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md) instead, go to **Settings > Shipping** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping** in the Shopify app, tick **Use SparkLayer shipping rates** and create your shipping methods.

### JavaScript options (for your developer)

JavaScript options are small scripts that change how the widgets behave. You don't need any of them to get started. Some settings are made in JavaScript, using [Spark Options](https://docs.sparklayer.io/help/storefront.md).

On WooCommerce, add them in **WooCommerce > Settings > Integrations > SparkLayer B2B**, under **Core Script Options**. If you use more than one option, combine them into one object.

**Add a checkout field, such as a delivery date**

This example adds a required **Preferred Shipping Date** field to the checkout and sets the link to your terms and conditions.

```javascript
{
  termsAndConditionsLink: "/policies/terms-of-service",

    checkoutCustomElements: [
      {
        name: 'shipping-date',
        translations: {
          en: {
            title: 'Preferred Shipping Date',
            detail: 'Shipping unavailable on weekends.',
          },
        },
        attributes: {
          required: true,
          type: 'date',
        },
      },
    ],
  }
```

**Redirect customers after they sign in**

This example sends signed-in customers who open a page matching `/account` to `/index` instead.

```javascript
{
   accountRedirect: {
      urlRegex: /\/account/g,
      goTo: "/index", // page to redirect logged in users to
   },
}
```

**Turn on dark mode for dark themes**

If your store uses a dark theme, dark mode changes the widgets' colours so text stays readable.

```javascript
{
     display: {
         darkTheme: true,
      },
  }
```

## FAQs and troubleshooting

**SparkLayer can't connect to my store**

Check that your store uses HTTPS, that the WordPress permalink setting isn't **Plain**, and that the REST API key has **Read/Write** permissions. If it still won't connect, [contact our support team](https://docs.sparklayer.io/help/support.md).

**A B2B customer can't see B2B prices**

Check that the customer's WordPress user has a `SparkLayer B2B` role, and that the product has a SKU with a price in the customer's price list. Then [check the customer has synced](#check-a-customer-has-synced).

**Where can I find more help?**

See [Troubleshooting](https://docs.sparklayer.io/help/troubleshooting.md) for common issues such as pricing problems, and [WooCommerce FAQs](https://docs.sparklayer.io/help/platforms/woocommerce/faqs.md) for questions about plans, products and orders. You can also [contact our support team](https://docs.sparklayer.io/help/support.md).