# Install SparkLayer on Magento

URL: https://docs.sparklayer.io/help/platforms/magento/install
Applies to: Magento

Install SparkLayer on Magento or Adobe Commerce 2.4.2+: add the module, connect the integration, assign B2B groups, add the widgets, then test an order.

> **Quick summary**
>
> - Your developer installs the SparkLayer Magento module. You then create the SparkLayer B2B integration in Magento and enter its credentials in the SparkLayer Dashboard at app.sparklayer.io.
> - A customer becomes a B2B customer when they're in a Magento customer group synced from SparkLayer, such as **B2B: Base**.
> - On Luma-based themes, you switch the widgets on in **Stores > Configuration > SparkLayer > B2B**. Other themes need a Magento developer.
> - Magento needs the SparkLayer Enterprise plan, Magento 2.4.2 or later and PHP 7.4 or later. You set B2B prices and ordering rules in the SparkLayer Dashboard, 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 Magento:

1. **Before you start**: Version, MSI, SKUs, payments, shipping and a developer
2. **Install**: Add the module and create the integration
3. **Connect**: Enter the credentials, then assign B2B groups
4. **Widgets**: Switch on for Luma; a developer for other themes
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?**
>
> Yes, for part of it. Installing the module is a developer task, and so is adding the widgets to a theme that isn't based on Luma. You can do the rest yourself, in the Magento admin and the SparkLayer Dashboard. Sections that need a developer are marked "for your developer".

## Before you start

Check these before you install. It's also worth reading [Magento limitations](https://docs.sparklayer.io/help/platforms/magento/limitations.md).

- **Magento Open Source or Adobe Commerce, version 2.4.2 or later, with PHP 7.4 or later.**
- **The Multi-Source Inventory (MSI) module turned on.** MSI is Magento's built-in stock management, and it's on by default in most Magento installs. Your developer can check.
- **A unique SKU on every product**, because SparkLayer stores B2B prices by SKU. To check, edit a product in **Catalog**: the **SKU** field is under **Product Name**.
- **A payment method.** On a test store, turn on an example payment method in **Sales > Payment Services**.
- **Shipping rules** set up in **Stores > Configuration > Delivery Methods**, or in SparkLayer's own [shipping](https://docs.sparklayer.io/help/ordering/shipping-rules.md), so orders can be placed.
- **A Magento developer or technical partner**, to install the module and fit the widgets to your theme. The module supports Luma and Luma-based themes out of the box. On other themes, your developer outputs the SparkLayer web components in place of Magento's product page and product list cards. They also load the SparkLayer script for B2B customers, and connect customer sign-in to it.
- **The SparkLayer Enterprise plan.**

Once SparkLayer is running, you'll mostly use three areas of Magento: **Catalog** for products and SKUs, **Customers** for B2B customers, and **Sales** for B2B orders.

## Install SparkLayer

Your developer installs the module. You then create the integration and turn SparkLayer on in the Magento admin.

1. Ask your SparkLayer account manager for access to the SparkLayer Magento module.
2. Ask your developer to install the module on your store. Installing a Magento module is a developer task.
3. In the Magento admin, open **SparkLayer B2B** in the main menu. The **SparkLayer B2B Integration Connection Status** page lists your store views.
4. For the store you want to connect, click **Create and Activate Integration** in the **Action** column.
5. Go to **Stores > Configuration > SparkLayer > B2B**. Under **General Configuration**, set **Enabled** to **Yes** for your store and click **Save Config**.

## Connect your store

Connect SparkLayer to Magento with the integration's API credentials. You don't need to write any code. If you're not sure how, [our support team](https://docs.sparklayer.io/help/support.md) can help.

1. In the Magento admin, go to **System > Integrations**, find **SparkLayer B2B** for your store and click **Edit**. The **Integration Details** section shows the **Consumer Key**, **Consumer Secret**, **Access Token** and **Access Token Secret**.
2. [Register for SparkLayer](https://app.sparklayer.io/register) to create your SparkLayer account.
3. 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 **Magento**.
4. Enter your store URL: the address of the site you're installing SparkLayer on, such as `www.mystore.com`.
5. Paste in the integration credentials from step 1 and click **Save**.
6. Wait a few seconds while SparkLayer connects to your store and sets up the module.

Your store is now connected, and SparkLayer starts syncing your products and customers. Next, put your B2B customers in a B2B group.

### Put customers in a B2B group

On Magento, you create customer groups in SparkLayer, not in Magento. SparkLayer then creates a matching customer group in Magento with the prefix `B2B`, such as **B2B: Base** or **B2B: VIP Customers**.

1. In the SparkLayer Dashboard, 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** to add another.
2. In the Magento admin, go to **Customers** and open a customer, or create one.
3. Set the customer's **Group** to the synced B2B group, such as **B2B: Base**, and save. 

You can manage a group's rules in SparkLayer once at least one customer is in 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 Magento customer ID, shown in **Customers** in the Magento admin.

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

How you add the SparkLayer widgets (the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md)) depends on your theme:

| Your theme | Who adds the widgets |
| --- | --- |
| **Luma, or based on Luma** | You. The module sets the widgets up for you: switch them on in the Magento admin. |
| **Any other theme** | Your Magento developer or technical partner. Magento stores and themes are often heavily customised, so the widgets are added in your theme code. Your developer can use the Luma setup as a reference. |

### Turn on the widgets for a Luma-based theme

1. In the Magento admin, go to **Stores > Configuration > SparkLayer > B2B**.
2. Under **Frontend Widget**, set **Enabled** to **Yes** and click **Save Config**.

The **Frontend Widget** section has these settings:

| Setting | What it does |
| --- | --- |
| **Enabled** | Turns the widgets on for the store view. |
| **Script URL** | The address of the SparkLayer script. By default, **Use system value** is ticked. |
| **Spark Domain** | The SparkLayer domain. By default, **Use system value** is ticked. |
| **Show for Related Products** | Adds the widget to the `catalog.product.related` layout block. |
| **Show for Upsell Products** | Adds the widget to the `product.info.upsell` layout block. |
| **Show in Product List Widgets** | Adds the widget to product widgets on CMS pages. |

The **Auth** section has a **JWT Token Lifetime (minutes)** setting, which is 10 minutes by default.

### Add the widgets to other themes (for your developer)

On a theme that isn't based on Luma, the widgets are added in your theme code. Pass these steps to your Magento developer or technical partner.

**Step 1.** **Add the Core Script**

Add the [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting) to your site's header, so SparkLayer turns on when a customer in a SparkLayer B2B group signs in. In the script, replace `yourstorehere` with your store's [site ID](https://docs.sparklayer.io/help/dashboard/account.md).

**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. Where it goes depends on your theme.

```javascript
<spark-pdp parent-id="{{id}}"></spark-pdp>
```

**Step 3.** **Add 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 when you install SparkLayer. If it isn't, add this snippet to the template that renders products on your collection pages:

```javascript
<spark-product-card parent-id="{{id}}"></spark-product-card>
```

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

Hide anything B2B customers shouldn't see, such as retail prices, quantity selectors, product options and buy buttons, by adding `data-spark="b2c-only"` to each of those elements. See the [frontend integration guide](https://docs.sparklayer.io/developers/frontend.md).

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

Add the [recommended starting CSS](https://docs.sparklayer.io/help/storefront/customising-design.md#recommended-starting-css) to your theme, then change the CSS variables to match your store's colours and fonts. 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 Magento 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 and choose each group's price lists, payment methods and order limits. 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 in a B2B group and check your prices. Place a test order with each payment method you offer. See [How B2B orders arrive in Magento](#how-b2b-orders-arrive-in-magento).
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 Magento

Every order goes to **Sales > Orders** in Magento. 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 Magento |
| --- | --- | --- |
| **Pay on Account** | Checks out without entering payment details. | **Pending**. Mark it as paid once you've received payment. |
| **Pay by Invoice** | Checks out without entering payment details. | **Pending**. Mark it as paid once you've received payment. |
| **Pay Online by Card** | Goes to the Magento checkout and pays straight away, with any payment method you've set up (such as card or PayPal). | **Processing**, 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 Magento admin or offline, for example by bank transfer.

Each order also has a **SparkLayer Order Information** tab, which shows:

| Section | What it shows |
| --- | --- |
| **Payment Method** | The payment method the customer used, such as Payment By Invoice. |
| **Customer Details** | The customer's **SparkLayer ID**, **E-mail** and **Accounting ID**. |
| **Discount Information** | Any SparkLayer discounts applied to the order. |
| **Line Item IDs** | The `sparkItemKey` and `sparkVariantId` for each line. |

## More settings on Magento

### 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 **Stores > Configuration > Inventory**.

### 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 Magento.

### SparkLayer shipping

By default, B2B orders use your Magento 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 Magento, add them in the **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

**The SparkLayer B2B groups don't appear in Magento**

Groups are created in SparkLayer and synced to Magento. Check that your store is connected at **Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app and that **Enabled** is set to **Yes** in **Stores > Configuration > SparkLayer > B2B**. If they still don't appear, [contact our support team](https://docs.sparklayer.io/help/support.md).

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

Check that the customer is in a synced B2B group in Magento, that the frontend widgets are set up for your theme, 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 [Magento FAQs](https://docs.sparklayer.io/help/platforms/magento/faqs.md) for questions about plans, products and orders. You can also [contact our support team](https://docs.sparklayer.io/help/support.md).