# SparkLayer Docs

> SparkLayer is a B2B eCommerce platform that adds wholesale ordering, customer-specific pricing, quoting, payment terms and self-service account features to existing online stores (Shopify, BigCommerce, Wix, WooCommerce, Magento) or to custom storefronts via its APIs, JavaScript SDK and the Ignite integration framework.

This file lists every page of the SparkLayer documentation with a short summary. Each link points to a Markdown version of the page. The complete documentation in one file is at https://docs.sparklayer.io/llms-full.txt, or one file per section:

- [Help Center](https://docs.sparklayer.io/llms/help.txt): Set up, configure and run SparkLayer on your store.
- [Developers](https://docs.sparklayer.io/llms/developers.txt): APIs, JavaScript SDK, templates and integration guides.
- [Ignite](https://docs.sparklayer.io/llms/ignite.txt): Build a SparkLayer integration for any commerce platform.
- [Developers: guides and API index](https://docs.sparklayer.io/developers/llms.txt): Every developer and Ignite guide in full, the facts for calling the APIs and a list of every API operation. Start here to build an integration.
- [API operations](https://docs.sparklayer.io/llms-api.txt): Every SparkLayer API operation in one compact list: method, path, summary, parameters and body fields, with links to the full reference and the OpenAPI specs.

## Using these docs

- Every page has a Markdown version: add `.md` to its URL, or request the page with `Accept: text/markdown`.
- Building on the APIs or SDK? Read https://docs.sparklayer.io/developers/llms.txt (developer guides in full plus every API operation) or the compact https://docs.sparklayer.io/llms-api.txt, and follow the facts below.
- Search and read the docs from an AI assistant or agent with the MCP server at https://docs.sparklayer.io/mcp (tools: `search_docs`, `get_page`, `list_pages`, `list_operations`, `get_operation`, `get_openapi_spec`).
- Help Center pages open with a "Quick summary" that answers the page's question; read it first.
- Pages marked with platforms in brackets (for example "Shopify only") apply only to those eCommerce platforms. Everything else applies to every platform.
- New to SparkLayer? Start with [How SparkLayer works](https://docs.sparklayer.io/help/get-started/how-sparklayer-works.md), then [Get started](https://docs.sparklayer.io/help/get-started.md). Terms are defined in the [Glossary](https://docs.sparklayer.io/help/glossary.md).
- Dashboard locations are written as **Area > Screen** with a link to https://app.sparklayer.io.

## Facts for building integrations

These apply to every call to the SparkLayer APIs. Use only what the docs and OpenAPI specs define.

- **Base URLs:** Live `https://app.sparklayer.io`, test `https://test.app.sparklayer.io`. Each environment has its own data and its own API keys.
- **Access:** API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
- **Access token:** `POST {base}/api/auth/token` with a `Site-Id` header and a JSON body (not form-encoded): `{"grant_type":"client_credentials","client_id":"…","client_secret":"…"}`. It returns `access_token`, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires.
- **Every request:** `Authorization: Bearer <access_token>` and `Site-Id: <site id>`, plus `Content-Type: application/json` when there is a body. Set a `User-Agent` that names your integration.
- **Errors:** RFC 7807 problem details: `title`, `status`, `detail` and an optional `errors[]` of `{ code, message, property }`. Some error responses have no body. Retry `5xx`, `429` (honouring `Retry-After`) and concurrent-update `409`s with exponential backoff; on `401`, get a new token once and retry; don't retry other `4xx` without changing the request.
- **Pagination:** Most list endpoints return everything. `GET /api/v2/price-lists` pages with `page` and `page_size` (up to 250) until `pagination.current_page` equals `total_pages`. `GET /api/v1/purchases` uses `limit` (up to 500) and `offset`: stop when a page has fewer than `limit` results.
- **Ground rules:** Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer `GET /api/v2/price-lists` over the deprecated v1. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code.
- **Ignite:** With Ignite, SparkLayer calls endpoints that your service implements (the Ignite spec), and your service calls the SparkLayer APIs above for everything else.
- **Read the docs as Markdown:** Add `.md` to any page URL. Index of every page: https://docs.sparklayer.io/llms.txt. Every API operation, compactly: https://docs.sparklayer.io/llms-api.txt. The developer guides in full: https://docs.sparklayer.io/developers/llms.txt.
- **OpenAPI specs:** `core`, `ordering`, `pricing`, `purchasing`, `stock`, `files`, `sync-log`: https://docs.sparklayer.io/openapi/<api>.yaml (also `.json`). Ignite: https://docs.sparklayer.io/openapi/ignite.yaml.
- **MCP:** Search and read these docs from your assistant with the docs MCP server at https://docs.sparklayer.io/mcp.

OpenAPI specs (index: https://docs.sparklayer.io/openapi/index.json; each is also published as `.json`):

- Core API: https://docs.sparklayer.io/openapi/core.yaml
- Ordering API: https://docs.sparklayer.io/openapi/ordering.yaml
- Pricing API: https://docs.sparklayer.io/openapi/pricing.yaml
- Purchasing API: https://docs.sparklayer.io/openapi/purchasing.yaml
- Stock API: https://docs.sparklayer.io/openapi/stock.yaml
- Files API: https://docs.sparklayer.io/openapi/files.yaml
- Sync Logging API: https://docs.sparklayer.io/openapi/sync-log.yaml
- Ignite endpoints: https://docs.sparklayer.io/openapi/ignite.yaml

# Welcome to SparkLayer

URL: https://docs.sparklayer.io/help

SparkLayer adds B2B ordering, customer pricing and payment terms to Shopify, BigCommerce, Wix, WooCommerce and Magento. Start here to find your way around.

> **Quick summary**
>
> - SparkLayer adds B2B (wholesale) ordering to your existing online store: trade prices, payment on account, quick ordering and a self-service account area for your business customers.
> - It runs alongside your retail store on [Shopify, BigCommerce, Wix, WooCommerce and Magento](https://docs.sparklayer.io/help/platforms.md).
> - New here? Answer 4 quick questions for [your own setup guide](https://docs.sparklayer.io/help/get-started/setup-guide.md), or follow [Get started](https://docs.sparklayer.io/help/get-started.md): 5 steps on the **Setup** checklist, from your first price list to your theme. Not on Shopify? Start with your [platform's install guide](#find-your-platform).
> - Want a hand? On every plan, our team installs SparkLayer's storefront widgets for you, free, and paid plans include onboarding sessions. See [Contact support](https://docs.sparklayer.io/help/support.md).

## New to SparkLayer?

Not sure where to start? Answer 4 quick questions and get [your own setup guide](https://docs.sparklayer.io/help/get-started/setup-guide.md): the guides that apply to your store, in the order you need them.

Once SparkLayer is installed, the **Setup** checklist takes you through setup in order. You create a price list, assign it to a customer group and add your first buyer. Then you add SparkLayer to your theme and publish it. On platforms other than Shopify, install SparkLayer with [your platform's guide](#find-your-platform) first.

If terms like price list or customer group are new to you, read **How SparkLayer works** first. It takes a few minutes.

- [Get started](https://docs.sparklayer.io/help/get-started.md): Set up SparkLayer in 5 steps, from your first price list to your theme
- [How SparkLayer works](https://docs.sparklayer.io/help/get-started/how-sparklayer-works.md): How it fits with your store, plus price lists, customer groups and the other essentials
- [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md): Test your setup, invite your first customers and go live
- [Get help setting up](https://docs.sparklayer.io/help/support.md): Free installation, onboarding sessions or a question for our team

## Find your platform

Installing SparkLayer is the first setup step, and it's different on each platform. Your platform's guide covers installation, setup and limitations. Everything else in the Help Center works the same on every platform.

- [Shopify](https://docs.sparklayer.io/help/platforms/shopify.md): Works with all Shopify plans. The free Basic plan is only on Shopify.
- [BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce.md): Works with BigCommerce Plus, Pro and Enterprise
- [Wix](https://docs.sparklayer.io/help/platforms/wix.md): Works with Wix Editor and Wix Studio
- [WooCommerce](https://docs.sparklayer.io/help/platforms/woocommerce.md): Early access. WooCommerce 9+, WordPress 6+ and PHP 8.2+
- [Magento](https://docs.sparklayer.io/help/platforms/magento.md): Magento 2.4.2+ and PHP 7.4+. Requires the Enterprise plan.

## Pulse for sales reps

**Pulse** is SparkLayer's workspace for sales reps. It puts every account, order, quote and invoice in one place. It also shows who needs attention today, which customers are due to reorder and the tasks to work through. Pulse is in early access.

[Explore Pulse](https://docs.sparklayer.io/help/pulse.md)

## What you can do with SparkLayer

- [Customer-specific pricing](https://docs.sparklayer.io/help/pricing.md): Give each B2B customer their own prices and price lists.
- [Self-service ordering](https://docs.sparklayer.io/help/storefront/interfaces.md): A B2B cart, checkout and account area on your existing store.
- [B2B payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md): Net terms, payment on account, invoices and quotes.
- [Order for customers](https://docs.sparklayer.io/help/sales-ordering.md): Let your sales reps place orders on behalf of customers.
- [Pack sizes & quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md): Set pack sizing, quantity breaks and unit of measure pricing.
- [Quick re-ordering](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md): Customers repeat past orders in a couple of clicks.
- [Shopping lists](https://docs.sparklayer.io/help/ordering/shopping-lists.md): Customers save lists of the products they buy regularly.
- [Pre-orders & back-orders](https://docs.sparklayer.io/help/storefront/stock-display.md): Control ordering when products are out of stock or coming soon.
- [Company teams](https://docs.sparklayer.io/help/customers/company-users.md): Customers invite colleagues to order from one shared account.

See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md) for what's included on each plan.

## Browse the Help Center

- [Guides](https://docs.sparklayer.io/help/guides.md): Step-by-step walkthroughs for common goals, such as Net 30 terms or a key account's own prices
- [Pricing](https://docs.sparklayer.io/help/pricing.md): Price lists, the price editor, quantity pricing and discounts
- [Customers & companies](https://docs.sparklayer.io/help/customers.md): Customers and customer groups, plus companies, their locations and invites
- [Sales reps](https://docs.sparklayer.io/help/sales-ordering.md): Order for customers, the Catalog, Counter mode and rep setup
- [Ordering & checkout](https://docs.sparklayer.io/help/ordering.md): Cart and checkout, payment methods, invoices, quotes and shipping
- [Storefront & products](https://docs.sparklayer.io/help/storefront.md): The interfaces your customers use, and how products display
- [Forms](https://docs.sparklayer.io/help/forms.md): Trade account applications and other forms, with approval workflows
- [Dashboard & settings](https://docs.sparklayer.io/help/dashboard.md): Find your way around SparkLayer, Orders, settings and your plan
- [Integrations](https://docs.sparklayer.io/help/integrations.md): Connect ERPs, accounting software and other apps
- [What's new](https://docs.sparklayer.io/help/whats-new.md): Monthly release notes

## Need help?

- [Contact support](https://docs.sparklayer.io/help/support.md): Email or message our team, see how fast we reply, or request free installation
- [Troubleshooting](https://docs.sparklayer.io/help/troubleshooting.md): Fixes for missing B2B prices, widgets not loading and checkout errors
- [General FAQs](https://docs.sparklayer.io/help/faqs.md): Platforms, cost, setup time and whether you need a developer
- [Glossary](https://docs.sparklayer.io/help/glossary.md): Every SparkLayer term in plain English

## Using an AI assistant?

Every page has a **Copy for LLM** button and a Markdown version (add `.md` to the address). Paste either into ChatGPT, Claude or another assistant. AI tools can start from [/llms.txt](https://docs.sparklayer.io/llms.txt), which lists every page with a one-line summary and a link to its Markdown version, or search and read the docs through the MCP server at `https://docs.sparklayer.io/mcp`.

Connecting an ERP, CRM or iPaaS through the SparkLayer API? See the [developer docs](https://docs.sparklayer.io/developers.md).


---

# What's new

URL: https://docs.sparklayer.io/help/whats-new

Monthly SparkLayer release notes listing new B2B features and improvements by version, such as Pulse, Counter mode, Companies and the new My Cart.

For earlier releases (June 2022 to September 2025), see the [release archive](https://docs.sparklayer.io/help/whats-new/archive.md).

> **Get the latest SparkLayer version**
>
> New stores use the latest version automatically. If you've pinned one, choose the latest under **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 and click **Save version**. The [frontend integration guide](https://docs.sparklayer.io/developers/frontend.md) explains how the Core Script works.

## October 2026

### Version 5.0

**New features**

**Pulse, for your sales reps**

Pulse is a workspace for sales reps in the SparkLayer widget. It shows who to contact today and why, their orders, quotes, carts and unpaid invoices, and how each account is trading. It's in early access on every paid plan with a sales agent seat. See [Pulse](https://docs.sparklayer.io/help/pulse.md) for what it does and to request access.

![Pulse – What's new](https://docs.sparklayer.io/images/help/whats-new/pulse-392419.webp)

**A new look for My Cart, My Account and sales agent ordering**

The SparkLayer widget has a new design. My Cart, My Account and the sales agent screens now share one look, so they feel like one product, and they're easier to read at a glance. 

![The new My Cart – What's new](https://docs.sparklayer.io/images/help/whats-new/new-my-cart-ab237e.webp)

- **My Cart** puts the search for products by name, SKU or barcode at the top, with the **Actions** menu beside it. Each line shows its stock, pack size, price per unit and RRP, and checkout runs in 4 clear steps: **Cart**, **Details**, **Review & Pay** and **Complete**. See [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md).
- **My Account** opens on the customer's recent orders, with their payment and order status, then their shopping lists, payment terms, unpaid balance and credit limit. See [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md).
- **Sales agent ordering** shows the accounts you opened last and your customers' recent orders, with a search by name, email or account number. In the cart, the **Ordering for** button shows whose order you're building: click it to switch customer. See [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md).

![My Account – What's new](https://docs.sparklayer.io/images/help/whats-new/new-my-account-1885e1.webp)

![Sales agent ordering – What's new](https://docs.sparklayer.io/images/help/whats-new/new-sales-agent-ordering-84cce8.webp)

**Catalog and Quick Order**

Browse your whole range in pictures and add products straight to the order. Sales reps see it as the **Catalog** tab, and your customers as the **Quick Order** tab. It has search, a collection filter, grid, list and matrix views, and quantities that follow your pack sizes and volume breaks. It's in early access on the Starter plan and above. See [Catalog and Quick Order](https://docs.sparklayer.io/help/sales-ordering/catalog.md).

![Catalog – What's new](https://docs.sparklayer.io/images/help/whats-new/catalog-53a206.webp)

**Counter mode**

A full-screen till for sales reps serving customers face to face, at a trade counter, in a showroom or on a trade show stand. Pick who's buying, then scan or tap products, starting from what that account usually buys. You can see the account's credit position as you go, then check out on Net terms, send a card payment link or submit a quote. Open it with **Counter** on the **Catalog** tab. It's in early access on the Starter plan and above. See [Counter mode](https://docs.sparklayer.io/help/sales-ordering/counter-mode.md).

![Counter mode – What's new](https://docs.sparklayer.io/images/help/whats-new/counter-mode-22952d.webp)

**Companies**

Your Shopify B2B companies and locations, in SparkLayer and kept in sync both ways. Set each company's customer group, price list, pay later, people and sales agents in one place. Split a big company into [locations](https://docs.sparklayer.io/help/customers/company-locations.md), such as stores or regions, each with its own settings where it needs them. Companies are in early access. See [Companies](https://docs.sparklayer.io/help/customers/companies.md).

![Companies – What's new](https://docs.sparklayer.io/images/help/whats-new/companies-fc3f51.webp)

**Payment method rules**

Add a discount or surcharge to a payment method when an order meets your conditions, or hide the method altogether. Conditions can use the order's sub-total, its items, the customer's available credit or the shipping destination. For example, you could add a 2% surcharge to card payments under £500. You could also hide **Pay on Account** when a customer has less than £500 of credit left. Set the rules for each customer group. Payment method rules are for Shopify stores on the Growth plan and above, with Core Script 4.13.0 or later. See [Payment method rules](https://docs.sparklayer.io/help/ordering/payment-method-rules.md).

## September 2026

### Version 4.10

**New features**

**Dark mode is now universally enabled**

In our latest version of SparkLayer, you can now enable dark mode on all the SparkLayer interfaces. Previously, this was limited to just the product pages - with our latest update dark mode now works in the [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) and the [My Account Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) to give a much more cohesive experience. To enable dark mode, see [Customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md).

![Dark mode is now universally enabled – What's new](https://docs.sparklayer.io/images/help/whats-new/whats-new-67a179.webp)

## August 2026

### Version 4.9

**New features**

**Add to Favourites**

Your B2B customers can now save products as they browse by clicking the heart icon on any product or collection page!

![Add to Favourites – What's new](https://docs.sparklayer.io/images/shared/product-display-9ca625.webp)

Saved products live in a new [Favourites](https://docs.sparklayer.io/help/ordering/favourites.md) section in My Account, right alongside shopping lists, where customers can return to them any time and add them straight to the cart. It's a lightweight way to mark products for later - no quantities or variants to manage - and it's personal to each customer.

![Add to Favourites – What's new](https://docs.sparklayer.io/images/shared/favourites-23d846.webp)

Learn more in [Favourites](https://docs.sparklayer.io/help/ordering/favourites.md).

**Tax-inclusive price display**

You can now show your B2B prices with tax included, clearly labelled "inc. tax", so buyers who think in gross terms see exactly what they expect. It's built for markets where gross pricing is the norm - common in Australia and across trade sectors selling to smaller businesses - and gives you far more flexibility in how you present pricing across different markets.

Importantly, this changes presentation only. Your prices are still stored, uploaded, and transacted net, and the tax your buyer actually pays is still calculated by your store's checkout at the point of purchase. Only the figure shown on your storefront changes.

- **Show the price your buyers expect** - display gross prices without changing how you upload or transact your pricing.
- **Control it per price list** - turn it on for the price lists that need it and leave the rest showing net, so you can serve different markets from one store.
- **Set your own rate per product** - supply a display tax rate per SKU, so reduced-rate and zero-rated products show correctly alongside standard-rate ones.
- **Clearly labelled throughout** - gross prices and the "inc. tax" label appear across product pages, cart, checkout, and order history, so there's no ambiguity about what a buyer is seeing.

You can turn on tax-inclusive display yourself: see [Show tax-inclusive prices](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-tax-inclusive-prices). [Learn more about displaying RRP pricing](https://docs.sparklayer.io/help/pricing/pricing-display.md)

**Improvements**

- **My Account discount display**

  When an order is placed with discounts applied, you can now see the discount total breakdown when viewing the order in the My Account.
- **A refreshed look across the dashboard**

  We've given several dashboard pages a visual update as part of standardising the experience - Price Editor, Product Sync, Discounts (including create and edit), and the Configurations pages all now share a cleaner, more consistent design.

## July 2026

### Version 4.7

**New features**

**Configure SparkLayer from the Dashboard - no code required**

Settings that previously had to be added to your theme's core script using JavaScript and JSON can now be managed visually from the new Options page in your SparkLayer Dashboard.

![Configure SparkLayer from the Dashboard - no code required – What's new](https://docs.sparklayer.io/images/shared/storefront-options-cf1605.webp)

Adjust general settings, translations, checkout fields, payment method order, My Account sections, custom slots, and analytics, then save as a draft and publish when you're ready. It works alongside your existing core script, so nothing you've already set up changes. Learn more in [Storefront options](https://docs.sparklayer.io/help/storefront/storefront-options.md)

**Standard checkout fields**

Customer Reference, PO Number, and Requested Shipping Date are now available as standard checkout fields.

![Standard checkout fields – What's new](https://docs.sparklayer.io/images/shared/cart-and-checkout-43a588.webp)

Because each one uses a known field ID, it maps to a structured place in your orders - the native Shopify PO Number field, a dedicated shipping date field, and the order notes - so they integrate more cleanly with Shopify, appear in your theme and template editor, and can be searched and filtered. [Learn more about cart and checkout options](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md)

**Improvements**

- **Wix dashboard and onboarding experience**

  We've redesigned our Wix dashboard to make it even easier for merchants to get setup! From right within Wix, you can now view available features, sync health & analytics, manage customer groups, manage price lists, and a new 'Quick Setup' page to get merchants live super fast
- **Upload Excel files to AI file upload**

  You can now upload Excel (.xlsx) files directly to AI file upload, alongside the existing CSV and PDF support. Customers and sales agents can turn a spreadsheet of products straight into an order, without converting it first. Learn more in [Intelligent Cart (AI)](https://docs.sparklayer.io/help/ordering/intelligent-cart.md)
- **More accurate quantity detection in uploaded files**

  AI file upload is now better at identifying the correct quantities in the files customers upload, making order creation from documents quicker and more reliable.
- **Duplicate forms in one click**

  You can now duplicate any form from within [SparkLayer Forms](https://app.sparklayer.io/forms)
- **Hide the Intelligent Cart features**

  If you'd prefer not to use the [Intelligent Cart (AI)](https://docs.sparklayer.io/help/ordering/intelligent-cart.md) features within the SparkLayer Cart, you can now hide them at **Settings > Configurations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations** in the Shopify app. See [Hide Intelligent Cart](https://docs.sparklayer.io/help/ordering/intelligent-cart.md#hide-intelligent-cart).

## June 2026

### Version 4.6

**New features**

**Shopping Lists just got a major upgrade**

Managing shopping lists is now faster and far more flexible! Products can be saved to a list straight from any product page, and lists can be fully managed from within the My Account area - including previewing, adding, and editing their contents. Your B2B customers and sales agents can also export any list as a CSV, making it easier to share and reorder across teams. [Learn more about shopping lists](https://docs.sparklayer.io/help/ordering/shopping-lists.md)

**Orders API - build and manage orders**

> **The Orders API is in beta**
>
> To be invited, email [support@sparklayer.io](mailto:support@sparklayer.io).

We've extended our Core API with a new Orders API, giving developers a programmatic way to build and manage orders. The new endpoints let API users create and manage shopping carts and turn them into SparkLayer orders in code - opening up use cases such as creating orders through external integrations, for example drop shipping. Any store with API access has this automatically. See the [API documentation](https://docs.sparklayer.io/developers/api/ordering/create-cart.md) and the [usage guide](https://docs.sparklayer.io/developers/api/ordering.md) to get started.

**Fetch customer-specific pricing via the API**

As part of the same release, a new endpoint lets API users fetch customer-specific pricing for products, so integrations can pull the exact prices a given customer sees. Learn more in the [API documentation](https://docs.sparklayer.io/developers/api/core/get-customer-specific-pricing.md).

**Improvements**

- **My Account / My Cart - Expand button moved to the user menu**

  The "Expand" button now lives in the user dropdown menu, freeing up space for more important actions within each page.
- **Clearer impersonation view for sales agents**

  When viewing as a sales agent, you can now see exactly which customer you're impersonating on every page, making it easier to keep track when ordering on a customer's behalf.

## May 2026

### Version 4.5

**New features**

**Export Purchase History to CSV**

You can now export orders (including quotes and any other purchase types) directly from the Activity view as a CSV file, ready for Excel or Google Sheets. Choose between an order-level summary or a full breakdown with every line item, and any filters you've applied carry through to the export. Available from the customer or sales agent view. Learn more in [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md). (Requires Spark-JS Version 4.4 and above)

![Export Purchase History to CSV – What's new](https://docs.sparklayer.io/images/help/whats-new/pika-1780500436153-1x-b06788.webp)

**Reply Directly from Your Inbox**

No more logging in just to reply to a message. You and your customers can now respond to order communications straight from your email inbox, with replies automatically captured in SparkLayer's Timeline. It works across all order types, making it effortless to keep conversations going - especially on mobile, when you're on the go. Learn more in [Timeline & communications](https://docs.sparklayer.io/help/customers/timeline.md). (Requires Version 4.3 and above)

**Improvements**

**Customer & Order Data in Forms**

You can now pull customer and order data (including quotes and any other purchase types) directly into your SparkLayer forms. Great for cases like returns forms, where shoppers can select from their previous orders and items without re-entering details, and sales agents can request customer data to be updated. Learn more in [Account credit request form](https://docs.sparklayer.io/help/forms/account-credit-request-form.md).

**Address improvements**

Entering addresses just got easier - especially for international buyers. Address forms now adapt their layout and name ordering to the selected country, and offer address search and auto-fill. The result is faster, more accurate data entry wherever your customers are based. Learn more in [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md). (Requires Version 4.5 and above)

**Improvements to Sales Agent Activity Filtering**

Sales agents get the same export options across all their customers, and, similar to the customer view, they can now filter by the new purchase type and quote status filters. Making it easy to reconcile orders, forecast inventory, or plan pre-orders. (Requires Version 4.4 and above)

> **Internal Customer API upgrades:** We've released V2 of our Customer API, now available to all Shopify stores (and in June we'll move the other platforms over). For customers who are already using the V1 Customers API, you can continue to use the V1 API for the next 6 months till the 1st of December 2026. The upgrade path is straightforward, and we’ll provide more information about the changes soon.

## April 2026

### Version 4.4

**New features**

**A better way to onboard customers.**

SparkLayer Forms is a flexible way to capture, review, and manage B2B information at every stage of the customer lifecycle — from first enquiry through to ongoing account management or even a contact form for your site.

It includes a workflow editor (on the Growth plan and above) that can tag customers automatically, make API calls to push new customers to your ERP, or even approve customers automatically when their tax ID is validated. See [Form workflow automations](https://docs.sparklayer.io/help/forms/workflows.md). Learn more in [Forms](https://docs.sparklayer.io/help/forms.md).

**Catalogs**

[B2B Catalogs](https://apps.shopify.com/sparklayer-b2b-catalogs) is a free SparkLayer app (for Shopify) that gives you control over which products are visible to different types of customers on your Shopify store. Whether you want to hide specific products from B2C customers, restrict certain items to B2B customers only, or show different product ranges to different customer groups - B2B Catalogs makes it easy to manage from your Shopify admin.

![Catalogs – What's new](https://docs.sparklayer.io/images/help/whats-new/20260415-044949-f663ef.webp)

**Sales agents' roles.**

Sales agent roles let you control what each sales agent can see and do in SparkLayer - so the right people have the right level of access. Instead of managing permissions individually, you can create reusable roles and assign them across your team. Available for anyone with sales agents. Learn more in [Sales agent ordering](https://docs.sparklayer.io/help/sales-reps/roles.md).

![Sales agents' roles. – What's new](https://docs.sparklayer.io/images/help/whats-new/whats-new-3aa228.webp)

**Custom email domain**

Improve brand recognition and deliverability with support for custom "from" email addresses (e.g. [store@mail.yourstore.com](mailto:you@yourstore.com)), helping ensure notifications match your brand. Available on Pro and Enterprise plans. Learn more in [Timeline & communications](https://docs.sparklayer.io/help/customers/timeline.md).

![Custom email domain – What's new](https://docs.sparklayer.io/images/help/whats-new/20260401-105203-fe967c.webp)

**Improvements**

- **Dashboard Customers and Sales Agent page** - New and improved visibility for customers, customers syncing and sales agents.
- **Disable specific email templates -** Through a minor template change, it is possible to disable a email template and this could be actioned based on logic. Learn more in [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md).
- **Package level invoicing for Xero/Quickbooks** - Invoices are now shown at package level rather than multiple invoices shown at the order level.
- **Company Users** is now available for all plans.

## March 2026

### Version 4.3

**Improvements**

- **Shopify Company support -** SparkLayer will automatically place orders under the correct Shopify company when a customer is attached to one. Learn more in our full guide, [Shopify Companies](https://docs.sparklayer.io/help/platforms/shopify/companies.md)
- **Multilingual Shopify Shipping support -** Support for multilingual shipping names when using Shopify shipping.

## February 2026

### Version 4.1

**New features**

**Payment Visibility within SparkLayer**

Cut down on support admin by letting your customers check their financial standing themselves.

![Payment Visibility within SparkLayer – What's new](https://docs.sparklayer.io/images/shared/payment-methods-959870.webp)

This new feature provides real-time account balances, payment statuses, and transaction histories directly in the My Account area. To read more see [Payment Methods](https://docs.sparklayer.io/help/ordering/payment-methods.md).

![Payment Visibility within SparkLayer – What's new](https://docs.sparklayer.io/images/shared/payment-methods-aa78f8.webp)

The key elements:

- Payment status is now visible within the order listing and the order details tab (Paid, Unpaid, Partially Paid)
- Transactions are now visible within the timeline section of the order.
- The balance shown in the Account section has now been updated based on payments.

This feature can be enabled easily via the [SparkLayer Dashboard](https://app.sparklayer.io/configuration/settings/general). Compatible with Shopify, Xero, and QuickBooks Online.

**Improvements**

- **Speed, Polish, and Performance Upgrades** (Version 4+)
  - **Speed Boost:** Enjoy snappier loading for products, carts, and accounts thanks to smarter caching.
  - **Visual Polish:** A cleaner, more refined look across the interface with improved layouts, spacing, and typography.
  - **Better Shopping Flows:** More reliable cart updates, smoother reordering, and a simplified quantity selector.
  - **Accessibility & Fixes:** Upgraded screen reader support, better right-to-left (RTL) language layouts, and a solid round of bug squashing.
- **Dashboard Price Lists and Customer Groups page** - New and updated design for the price lists and customer groups page, we'll be rolling out more pages in this design over the coming months.
- **Improved Product Selection Dropdowns -** Invalid selections on Product Details Page dropdowns are now hidden rather than disabled, creating a cleaner interface for your customers. (Version 3.17.0+)

## January 2026

### Version 3.15

**Improvements**

- **Discounts - Exclude Specific Customers**

  Discounts can now exclude specific customers using email addresses or accounting IDs, giving more control over who can use each promotion. [Learn more about discounts](https://docs.sparklayer.io/help/pricing/discounts.md)
- **Quotes - New Email Notifications**

  We’ve added three new quote emails that the customer will receive, to make it clearer when a quote has been created or updated:

  - First response from a Sales Agent to a quote request
  - Subsequent quote updates made by a Sales Agent
  - New quote created by a Sales Agent and sent to a customer

See the [complete list of quoting emails and their triggers](https://docs.sparklayer.io/help/ordering/quoting.md#email-notifications-sent).

## December 2025

### Version 3.14

**New features**

**Xero and QuickBooks Online integrations announced**

We announced SparkLayer's Xero and QuickBooks Online integrations. They're now live, on the Pro plan and above: see [Xero](https://docs.sparklayer.io/help/integrations/accountancy/xero.md) and [QuickBooks Online](https://docs.sparklayer.io/help/integrations/accountancy/quickbooks.md).

![Xero and QuickBooks Online integrations – What's new](https://docs.sparklayer.io/images/help/whats-new/20251212-105928-20ef78.webp)

**Timeline & Communications**

Timeline & Communications has expanded beyond Quotes and is now available across **all supported order types**. Messages, internal notes and order updates are brought together in one clear, chronological timeline, giving your team and customers a unified place to track communication and activity as orders progress.

The result is a consistent, streamlined experience - whether you’re managing standard B2B orders, quotes, or draft orders created by Sales Agents. Learn more in [Timeline & communications](https://docs.sparklayer.io/help/customers/timeline.md)**.**

## November 2025

### Version 3.14

**New features**

**Dashboard Design Updates**

We’ve refreshed the SparkLayer Dashboard with a streamlined sidebar that makes navigation simpler, faster, and more organised.

![Dashboard Design Updates – What's new](https://docs.sparklayer.io/images/shared/get-started-272f13.webp)

- **Customer and Product Sync** now sit under **Integrations**, alongside platform connection, Partner Integrations, and Widgets.
- **Discounts** is now grouped with **Pricing**, alongside price lists and Price Editor, reducing clutter and keeping pricing tools together.

The result is a **cleaner layout** and **clearer structure** that lets you focus on what matters most - your store’s performance.

**Improvements**

- **Stock Display - Option to hide pre-order status**

  A new configuration within customer groups allows you to hide the “pre-order” stock status from customers.

## October 2025

### Version 3.14

**New features**

**Quote Status Improvements**

You can now **filter quotes by individual status**, giving you greater granularity and control when managing quotes. Previously shown in a single view, quotes can now be broken down by stage for easier tracking and follow-up.

![Quote Status Improvements – What's new](https://docs.sparklayer.io/images/help/whats-new/20251105-144324-8344e6.webp)

Custom statuses are automatically included, and a new chevron indicator shows when more filters are available to scroll through. Statuses have also been reordered to reflect logical quote progression for a smoother workflow.

**Shipping Restrictions by State/Province**

You can now limit shipping methods to specific **states or provinces** within the US, Australia and Canada, allowing more precise regional control. This makes it easier to tailor delivery options, manage exclusions, and align shipping availability with your operational areas.

![Shipping Restrictions by State/Province – What's new](https://docs.sparklayer.io/images/help/whats-new/20251028-152712-cb7733.webp)

You can configure this directly under **Settings → Shipping Methods.**

**Improvements**

- **Quotes - CC Notifications to Child Company Users**

  Quote notifications sent to parent company users now CC child company users to keep both informed.
- **AI Cart Import - Support for Multiple SKU Columns**

  AI Cart Import now supports files with multiple SKU columns (e.g. vendor SKU and product SKU) and auto-detects the correct one.
- **Cart - Display Unit of Measure**

  Products with a single unit of measure now show it directly on the cart line item, without needing to hover.

Looking for older updates? Browse releases from June 2022 to September 2025 in the [release archive](https://docs.sparklayer.io/help/whats-new/archive.md).


---

# Release archive

URL: https://docs.sparklayer.io/help/whats-new/archive

SparkLayer release notes from June 2022 to September 2025, including the Quoting Engine launch, the BigCommerce integration and barcode support.

SparkLayer release notes from June 2022 to September 2025, newest first. For the last 12 months of updates, see [What's new](https://docs.sparklayer.io/help/whats-new.md).

## September 2025

### Version 3.12

**Improvements**

- **Shopify - Languages: support for product data translations**

  SparkLayer now has the ability to sync product data translations and show product data in the customer's language. This is currently only supported for Shopify stores. Please contact us if you'd like us to enable it on your store. [Learn more about languages and custom text](https://docs.sparklayer.io/help/storefront/languages-and-international.md)
- **Shopify - Number of Cart Lines Supported**

  Previously we had a limit of 250, we now support 350 line items or 500 line items (by request due to the performance of the Shopify APIs).
- **BigCommerce - Support for Combined Order Limit Rules**

  You can now use both SparkLayer’s product minimum and maximum order limit rules alongside the native BigCommerce rules, giving greater order management flexibility.
- **BigCommerce - Support for Custom Order Visible ID**

  You can now use a custom order ID instead of the standard BigCommerce-generated ID. This is useful for matching order numbers with back-office systems (e.g. ERP) to ensure consistency across platforms.
- **BigCommerce - Discount Rules Based on Product Properties**

  Discount rules can now check additional BigCommerce product properties when determining if a discount should be applied, such as; categories, brand ID, condition, UPC and search keywords.
- **Wix - Removal of RRP Field from Sync**

  The RRP field has been removed from syncing to prevent it from displaying on frontend widgets. A product resync will be required for the change to take effect.
- **Barcodes - Available on Invoices, Quotes & Emails**

  You can now add barcodes on Invoices, Quote PDFs and emails.
- **Sales Agent - “Submit Quote” button update**

  Sales Agents will now see a “Submit Quote” button instead of “Request Quote” during the quoting process, making the action clearer.
- **SparkLayer Core Script - Enhanced Error Codes**

  Error codes have been added for custom SparkLayer Options hook issues, making it easier for you to identify and resolve the cause of errors more quickly.
- **Activity Section - Quote Status Update**

  The Activity section now shows the “Quote Status” instead of “Quote”, with the column below displaying the actual status (e.g. _Awaiting merchant”_).
- **ERP Integration updates - Cin7, Brightpearl, Linnworks & Unleashed**

  Our ERP integrations have been improved so you can now view connection status, last sync, and any issues via **Settings → Integrations → Partner Integrations**, making it easier to resolve data syncing problems.

## August 2025

### Version 3.10

**Improvements**

**Use custom order IDs**

It's now possible to use a **custom order ID** instead of the standard order ID generated from Shopify. A typical use-case is customising the Order ID to match order numbers generated from a back-office system (e.g. an ERP), ensuring consistency across systems.

![Use custom order IDs – What's new](https://docs.sparklayer.io/images/shared/metafields-e314b4.webp)

When the "Visible ID" is set, this will then take effect when the customer views their orders from the [My Account Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md). To enable this, please see [Shopify metafields & data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md).

**Show a message at a cart line-item level**

![Show a message at a cart line-item level – What's new](https://docs.sparklayer.io/images/shared/custom-slots-de8752.webp)

Extending upon our [Custom Slots ("Targets")](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md) , you can now display a custom slot on a cart line-item level, such as a message that references the product name and ID ("slug"). This gives a powerful new way to add further customisation to the shopping cart for your B2B customers.

## July 2025

### Version 3.10

**New features**

**Discount Engine Improvements**

![Discount Engine Improvements – What's new](https://docs.sparklayer.io/images/help/whats-new/kn0yv9zxguvbursdd4omw-20250721-110750-57b425.webp)

We're excited to announce a range of major improvements to the SparkLayer [Discount Engine](https://docs.sparklayer.io/help/pricing/discounts.md), including the ability to:

- Set advanced requirements and rewards. [Learn more about discounts](https://docs.sparklayer.io/help/pricing/discounts.md)
- More extensive "free products" promotions. [Learn more about discounts](https://docs.sparklayer.io/help/pricing/discounts.md)

The updates now allow you to configure discounts that apply on more advanced criteria such as matching a specific "tag" or "vendor" (within Shopify), and the ability to set rewards that include multiple free products. These changes now position SparkLayer as having one of the most advanced B2B promotions engines available - we look forward to seeing how creative our customers will be using this! [Learn more about discounts](https://docs.sparklayer.io/help/pricing/discounts.md)

**Improvements**

- **Invoices - Option to display RRP**

  You can now choose to show the Recommended Retail Price (RRP) on SparkLayer [Invoices](https://docs.sparklayer.io/help/ordering/invoices.md), giving your customers greater visibility on pricing.
- **Cart - Clearer messaging when stock is limited**

  Customers will now see clearer messaging if they try to add more items to their cart than are available in stock, helping reduce confusion during the ordering process.

## June 2025

### Version 3.9

**New features**

**Katana Integration**

We're excited to announce our official integration with Katana, a leading inventory management solution!

![Katana Integration – What's new](https://docs.sparklayer.io/images/shared/tgn0yj2ee6vnbjszw86st-20250604-124134-bb1039.webp)

If you're using Katana to manage your back-office operation, you can now integrate your B2B pricing and customer data directly with SparkLayer. Learn more in [Katana](https://docs.sparklayer.io/help/integrations/erps/katana.md)

**Onboarding Landing Page**

A great way to encourage your customers to use your new B2B store is to **explain the benefits**. To help you get started, you can use our ready-made "onboarding landing page" that gives a great overview of the features to your customers. [Learn more about launching SparkLayer](https://docs.sparklayer.io/help/get-started/launching.md)

![Onboarding Landing Page – What's new](https://docs.sparklayer.io/images/shared/launching-8eca09.webp)

**Improvements**

- **My Account - Tax Display**

  When a customer places an order, they can now see their full tax breakdown when viewing their order details within the [My Account Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md)
- **Shopify - New Customer Accounts URL redirect**

  If you're using Shopify Customer Accounts, you can now configure which URL to send a customer to directly via your Shopify admin. In your Shopify admin, go to Settings, Checkout, and within [Configurations](https://admin.shopify.com/settings/checkout#checkoutprofiles), click "Customize" and you'll see a new field "Redirect Path" within the "B2B Customers Redirect" extension.
- **Checkout – Support for Tax ID Requirements**

  Merchants can now collect the required tax ID details at checkout, ensuring orders to countries with strict import rules can be completed in Shopify. [Learn more about cart and checkout options](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md)
- **CSV file upload**

  When importing a CSV file into the [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md), products will be added to the cart in the same order as listed in the CSV file.
- **New Languages**

  We now have support for Latvian on the [Frontend Interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md)
- **Duplicate Discounts**

  It's now possible to create multiple discounts with the same configurations, making setup faster for similar pricing rules. [Learn more about discounts](https://docs.sparklayer.io/help/pricing/discounts.md)
- **Checkout - Option to disable**

  You can now fully disable the checkout process and only show the "Request Quote" option, ideal for quote-only workflows. [Learn more about customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md)
- **Sales Agent - Auto sign-in after Customer Creation**

  Sales agents are now automatically signed in as the customer after creating them, removing the need to search and impersonate separately.

## May 2025

### Version 3.9

**New features**

**SparkLayer Intelligent Cart**

SparkLayer Intelligent Cart introduces a revolutionary new way for your B2B customers and sales teams to build orders quickly and effortlessly using the power of AI.

The magic lies in its simplicity: files and emails containing order details (such as SKUs, barcodes, and quantities) can be uploaded or emailed directly to SparkLayer, instantly creating a shopping cart. In addition, live barcode scanning is supported, providing powerful, fast ways to build orders without manually browsing and searching for product. Learn how Intelligent Cart works in [Intelligent Cart (AI)](https://docs.sparklayer.io/help/ordering/intelligent-cart.md).

### Version 3.8

**New features**

**Cart Search**

We've just given our search tool a massive upgrade, making it even easier for your customers to add items to an order!

The Search tool allows customers to **search by a range of criteria** including product name, product SKU, product variant name, SKU, and barcode.

The tool also handles mis-spellings and "partial matching", ensuring results are delivered where possible and allowing for a more user-friendly search. To learn more about how it works and how to enable it, see [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md).

## April 2025

### Version 3.7

**New features**

**The SparkLayer Quoting Engine**

We’re excited to announce the launch of the new [SparkLayer Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md) , designed to transform how your sales team and wholesale customers manage quotes.

![The SparkLayer Quoting Engine – What's new](https://docs.sparklayer.io/images/help/whats-new/6wzpfqy98oz0zjrjdicgl-20250412-131624-0fc46a.webp)

Built to simplify the entire "quote-to-order" process, it helps reduce manual work, speed up order conversion, and create a better buying experience.

With the [SparkLayer Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md), you can:

- Let customers build and submit quote requests directly from your store
- Enable your sales team to edit quotes, apply discounts, and set expiry dates
- Keep all communication in one place with a shared conversation timeline
- Seamlessly convert approved quotes into ready-to-process orders
- Notify customers and sales teams automatically with emails and special workflows
- ... and a lot more!

Whether you’re handling high-volume B2B orders or need more control over pricing negotiations, the [SparkLayer Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md) brings everything into one streamlined flow, all designed to save time, reduce friction, and strengthen customer relationships.

If you'd like to give it a try, head over to the [plan page in the SparkLayer Dashboard](https://app.sparklayer.io/settings/plan) where you can add it to an existing plan or as an exclusive addon. You can also learn more about how it works in [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md).

**Improvements**

- **Integration with Intuitive Shipping**

  We've released our new integration with shipping application, [Intuitive Shipping](https://docs.sparklayer.io/help/integrations/customer-experience/intuitive-shipping.md) making it even easier to connect SparkLayer to their dynamic shipping rate solution
- **Pre-orders and stock display**

  We've improved how stock is shown in the [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) when a product is on pre-order. If a customer orders more than is in active stock, it will now clearly show what stock is available and what is on pre-order

![Pre-orders and stock display – What's new](https://docs.sparklayer.io/images/help/whats-new/whats-new-4b0e53.webp)

## March 2025

### Version 3.7

**New features**

**SparkLayer Analytics**

We're excited to announce a major advancement in how you can report on your B2B sales and performance! We’ve partnered with the leading analytics experts, Conjura, to add unparalleled operational and sales visibility to your SparkLayer account.

![SparkLayer Analytics – What's new](https://docs.sparklayer.io/images/help/whats-new/sparklayer-screen-42a38c.webp)

Learn more about [SparkLayer analytics](https://www.sparklayer.io/analytics/), where you can also arrange a demo to see how it can fit your business needs.

**Automatic metafield creation**

Metafields are a powerful way to customise the functionality of your B2B store, allowing you to configure additional data such as [pack sizing](https://docs.sparklayer.io/help/storefront/quantity-rules.md), [rrp prices](https://docs.sparklayer.io/help/pricing/pricing-display.md), and much more. With our latest update, we've made it really easy to quickly add metafields to your Shopify store without needing to manually configure them within your Shopify admin.

![Automatic metafield creation – What's new](https://docs.sparklayer.io/images/help/whats-new/sparklayer-metafields-4a2782.webp)

To get started, head over to the [SparkLayer Dashboard](https://app.sparklayer.io/configuration/integrations/platform) or learn more in [Metafields](https://docs.sparklayer.io/developers/data/metafields.md).

**Improved Shopify B2B Login Page**

We've greatly improved our free [Shopify B2B Registration & Login](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md) template, making it really easy for you to add a login and signup form to your Shopify store.

![Improved Shopify B2B Login Page – What's new](https://docs.sparklayer.io/images/help/whats-new/sparklayer-screen-0d8c65.webp)

The improvements include full control over the design and content, the ability to set different actions when a customer applies, and much more! Learn more in [Shopify B2B registration & login](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md)

**Improvements**

- We've added the following additional [Custom Slots ("Targets")](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md)
  - Cart Shipping Step
  - Cart Payment Step
  - Account > Purchase Summary Header
  - Account > Purchase Summary Footer
- For our SDK, we've added a `onCartLoad`as an additional function that can be used when the cart is loaded. Read more in [SDK guide](https://docs.sparklayer.io/developers/javascript-sdk/guide).

### Version 3.6

**New features**

**Sales Agents - Add custom item**

We've released a major improvement to our [Sales Agent Ordering](https://docs.sparklayer.io/help/sales-ordering.md) tool that your sales team are going to love - the ability to add custom items to a B2B order!

![Sales Agents - Add custom item – What's new](https://docs.sparklayer.io/images/help/whats-new/sparklayer-screen-ecce87.webp)

Our new "Add custom item" feature lets your sales agents add additional items to a customer's order that sit outside of your general product catalogue. Use-cases could include adding custom instructions or details specific to an order, additional products (that don't have a specific SKU), or any custom item that needs to be associated with an order. Items can be added at a specific cost or at a zero cost value. Learn more in [Sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md)

**Improvements**

- **My Account - Order details**

  When viewing an order from the [My Account Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md), products that have variants (e.g. colour, size) will show the full variant information (previously this wasn't visible).

## February 2025

### Version 3.5

**New features**

**SparkLayer Invoices**

It's here... one of our most requested features of all time has arrived: _SparkLayer Invoices!_

The [SparkLayer Invoices](https://docs.sparklayer.io/help/ordering/invoices.md) feature allows you to automatically generate professional invoices that your customers can easily download, directly from their My Account.

![SparkLayer Invoices – What's new](https://docs.sparklayer.io/images/help/whats-new/vwiz0lwyo92ypypy7v2fu-20250215-114518-718676.webp)

SparkLayer's invoicing feature **removes the need** for third-party invoicing tools or apps and offers a seamless way to manage and share invoices with your B2B customers. Once you've enabled invoices via the setting detailed above, the process for viewing and downloading invoices is simple for your customers: they view and download them from **My Account**.

Interested in trying out SparkLayer Invoices? Learn more in [Invoices](https://docs.sparklayer.io/help/ordering/invoices.md).

### Version 3.3

**New features**

**Shipping discounts**

It's now possible to set shipping discounts when using SparkLayer [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md)! This has been one of our most requested features for our Discount Engine, and it gives you the option to set a range of different shipping discount types. From percentage off and fixed discounts, through to setting a specific shipping cost when the discount is applied.

![Shipping discounts – What's new](https://docs.sparklayer.io/images/help/whats-new/sparklayer-screen-c10fd0.webp)

Using this feature does require enabling the SparkLayer [shipping system](https://docs.sparklayer.io/help/ordering/shipping-rules.md) and you can learn more in [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md).

**Improvements**

- **Sales Agents - Creating New Customers**

  For Sales Agents with "Administrator" privileges, when inviting a new customer via SparkLayer, it's now possible to disable the "Invite" email that is sent to the customer. This is available for all merchants using Shopify. Learn more in [Sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md)

### Version 3.2

**New features**

**Show RRP prices only (for in-store shopping)**

If you manage orders in physical locations with customers (e.g. in store), it's possible to enable a setting that sets the SparkLayer [Frontend Interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) to **only** show the RRP (MSRP) prices when browsing and adding items to an order.

This is especially useful if you need to "obscure" your B2B prices from view and you only want to show the full retail prices.

Use-cases could include:

- In-store customer visits where an order needs to be placed and the customer must only be able to see the retail (RRP) prices
- Sales teams who are placing orders on behalf of customers (e.g. on the road) and only the retail (RRP) prices must be seen

Learn more about how this works in [How prices are shown](https://docs.sparklayer.io/help/pricing/pricing-display.md).

## January 2025

### Version 3.1

**New features**

**Sales agents - custom shipping methods**

One of the most requested features for our [Sales Agent Ordering](https://docs.sparklayer.io/help/sales-ordering.md) tool is to allow sales agents to make changes to the shipping costs during the checkout. We've now released the ability for sales agents to set custom shipping prices for any orders they place on behalf of their customers.

To learn more about how this works, see [Sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md).

**Order searching and filtering by date**

It's now possible for B2B customers to search and filter orders by date range within the [My Account Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md). This is a great way to quickly see orders based on specific criteria and time period, making it easier to keep track of order activity.

![Order searching and filtering by date – What's new](https://docs.sparklayer.io/images/help/whats-new/whats-new-54155f.webp)

To see this in action, click "View All" within "Recent Activity" and you'll see the option to search and filter your orders.

**Improvements**

**Mobile layout improvements**

We've made improvements to the [Cart & Checkout](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md) to better support smaller (mobile) devices. When a B2B customer is using SparkLayer on these devices, the interface will now show more line items and offer an easier way to navigate between checkout steps.

![Mobile layout improvements – What's new](https://docs.sparklayer.io/images/help/whats-new/whats-new-2dbb07.webp)

**Shopify - improved handling of B2B prices**

> **Please note**
>
> From 1st February 2025, this feature is enabled by default. If you started using SparkLayer before this date and you'd like to enable this on your Shopfy store, please [contact us](https://docs.sparklayer.io/help/support.md) and our team will action this for you.
>
> This is an optional feature and it is not mandatory to enable.

We've improved how SparkLayer handles pricing in Shopify, removing the need for B2B pricing to be applied as a "discount". When a B2B customer now places an order, the price shown against a product will exactly match the B2B pricing you set via SparkLayer [Pricing](https://docs.sparklayer.io/help/pricing.md).

To illustrate the difference, the screenshot below shows how pricing was calculated previously (using a discount against the line item product price)

![Shopify - improved handling of B2B prices – What's new](https://docs.sparklayer.io/images/help/whats-new/whats-new-322fa5.webp)

With the latest change, the price shown will exactly match your B2B pricing without needing to apply a discount.

![Shopify - improved handling of B2B prices – What's new](https://docs.sparklayer.io/images/help/whats-new/whats-new-baca9d.webp)

**Shopify - support for new customer accounts**

If you're using [Shopify](https://docs.sparklayer.io/help/platforms/shopify.md) and you'd prefer to use Shopify's new "Customer Account" feature, SparkLayer is now fully compatible. This means that SparkLayer can now work with Shopify stores that use either new "Customer Accounts" or classic "Legacy Accounts". To learn more, read [Installing SparkLayer on Shopify](https://docs.sparklayer.io/help/platforms/shopify/install.md).

## December 2024

### Version 2.1.0

**New features**

**Change ownership status in the Dashboard**

If you have multiple users invited to your [Dashboard](https://docs.sparklayer.io/help/dashboard.md), you can now easily transfer ownership to another user. This is especially useful if you're initially setting up SparkLayer and you want another user to manage the ongoing account management.

![Change ownership status in the Dashboard – What's new](https://docs.sparklayer.io/images/help/whats-new/whats-new-a8febb.webp)

To learn more about how this works, head over to [Account settings](https://docs.sparklayer.io/help/dashboard/account.md).

## November 2024

### Version 2.1.0

**New features**

**Integrating Google Analytics with SparkLayer**

If you're looking to track key events in Google Analytics (GA4) or Google Tag Manager (GTM) through SparkLayer, you can now set this up directly in your integration. This will help you capture valuable B2B events like "add to cart" "checkout," and "purchase" actions. Learn more in [Technical information](https://docs.sparklayer.io/developers/frontend/technical-information.md)

**New Email Notifications for Company Users**

We've now added the ability for Company Users to receive emails when "Limited Users" submit an order for a review. Email notifications are sent to both the "main" and "limited" Company Users at key stages of the order review process, without requiring them to be logged in. You can learn more about how this works in [Company users](https://docs.sparklayer.io/help/customers/company-users.md)

## October 2024

### Version 2.0.8

**New features**

**Product Matrix Interface**

We've introduced a major update to our [Frontend Interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) that now lets you convert your product pages into a special "product matrix" table view, making it even easier for your customers to order products!

If your products come in multiple variant types (e.g. colour and size), it's a great way to allow customers to quickly see all variants available and purchase them. To learn more about how this works, please see [Product matrix](https://docs.sparklayer.io/help/storefront/interfaces/product-matrix.md).

**Order details**

When viewing an order within the [My Account Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md), if an order has more than 10 unique items, a "View all" link will now show allowing the customer to see all items in one go.

![Order details – What's new](https://docs.sparklayer.io/images/help/whats-new/whats-new-ead74d.webp)

## September 2024

### Version 2.0.2

**New features**

**Custom checkout fields - support for new fields**

If you need to collect additional data from your B2B customers during the checkout, our [custom checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md) now supports the ability to add drop-down menus ("select" menus).

For example, you may want to give customers a list of options to choose from to include in their order and it's even possible to group the options with different headings. You can learn more about how this works in [Cart & checkout](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md).

**Stock display improvements**

> **Please note**
>
> This feature requires being on the latest version of SparkLayer. To benefit from our latest updates, please upgrade your [SparkLayer Core Script](https://docs.sparklayer.io/developers/frontend.md).

It's possible to display [stock levels](https://docs.sparklayer.io/help/storefront/stock-display.md) to your B2B customers when they browse your store, giving them visibility of your inventory. Our latest update now gives you even more flexibility and has a number of major improvements.

![Stock display improvements – What's new](https://docs.sparklayer.io/images/help/whats-new/whats-new-1bdd8a.webp)

Firstly, it's now possible to display stock levels on a per-customer group basis. For example, you may have some customer groups that you don't want to show inventory to or you may want to configure specific stock settings.

You can also now hide and show the specific inventory count and just show a stock status (e.g. `In stock` versus `In stock [100 available].`) Beyond this, we've also simplified how you can manage max/low/last stock levels and you can learn more in [Customers](https://docs.sparklayer.io/help/customers.md).

**Improvements**

- **My Account Addresses**

  When adding or editing an address within the My Account area, the `First Name` and `Last Name` fields are now mandatory.

## August 2024

### Version 1.36.16

**New features**

**Line Item Tax Support**

![Line Item Tax Support – What's new](https://docs.sparklayer.io/images/help/whats-new/screenshot-2024-08-27-at-190553-b1a385.webp)

If you sell products that have different tax requirements, you'll like our latest update! We've just released full support for "line item tax", ensuring your B2B customers see fully accurate tax calculations when checking out.

This feature is ideal if you have more complex tax requirements for your catalogue (e.g. you're selling coffee, children's clothing, or products that have varying tax obligations).

You can see a full overview of how it works in [How tax works at checkout](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md).

**Improvements**

- **Sales Agents within the SparkLayer Dashboard**

  Based on customer feedback, we've made it easier to access Sales Agents within the SparkLayer Dashboard. You'll see this in the main navigation when signing in, or you can [open Sales Agents in the SparkLayer Dashboard](https://app.sparklayer.io/sales-agents).

## July 2024

**New features**

**B2B Discount Engine!**

It's here... our most request feature EVER! The [SparkLayer Discount Engine](https://docs.sparklayer.io/help/pricing/discounts.md).

Our new Discount Engine immediately unlocks a range of discount rules, with more to come in the future. Right now, you'll be able to set up:

- **Order-level discounts:** eg, spend $1,000 and get 10% off, spend $2,000 and get 15% off
- **Percentage and fixed discounts:** eg, 20% off an order total, $100 off an order total
- **Coupon codes:** eg, enter code NEWCUSTOMER and get 5% off
- **Scheduled discounts:** eg, start discount today and end it on a specific date and time
- **Customer-specific discounts:** eg, only allow customer group ‘b2b-vip’ qualify for the discount

You can see a full overview of what’s possible in [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md).

**Custom slots (add custom code)**

Custom slots have arrived! You can now add custom code to a range of the SparkLayer [Frontend Interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) allowing you to customise the B2B experience for your customers.

It's a great way to further enhance your B2B customer experience and use-cases could include displaying promotional messages, links to pages within your store, and much more! [Learn more about custom slots](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md)

**Improvements**

- **Purchase history re-ordering**

  When viewing the Purchase History in the [My Account Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md), you can now add individual items directly to any order

## June 2024

**New features**

**File uploads (checkout and product-level)**

We're excited to announce the launch of one of our top 5 most requested features, file uploads! As of today, your B2B customers can now upload file attachments during the checkout process, allowing you to capture additional information such as Purchase Orders, custom files (e.g. for personalisation) and much more.

And there's more! In addition to file uploads during the checkout, you can now configure product-level file uploads! Learn more in [Cart & checkout](https://docs.sparklayer.io/help/ordering/checkout-fields.md).

**Stock location support ("inventory locations')**

As brands scale their operations and build out more advanced inventory management processes, it’s very common to see multiple ‘locations’ where inventory is managed. This could be based on geographic location (eg by country) or by more niche use cases specific to a brand’s internal workflows, like routing stock based on what type of customer is ordering.

![Stock location support ("inventory locations') – What's new](https://docs.sparklayer.io/images/help/whats-new/whats-new-19c4c4.webp)

Stock locations allow you to specify which stock (or "inventory") locations you want your B2B customers to use stock from. If your B2B store is set up with **multiple stock locations** (e.g. by geography), it's a great way to ensure your B2B customers are purchasing stock from the correct locations. Learn more in [Customers](https://docs.sparklayer.io/help/customers.md)

## May 2024

**New features**

**New Customer Groups interface**

We've just released a major improvement to the [Customers](https://docs.sparklayer.io/help/customers.md) area of the [SparkLayer Dashboard](https://app.sparklayer.io/customers/groups), making it easier to manage your B2B customer rules! We've completely reworked how your customer groups are displayed with a new and improved way to quickly manage all your customer groups settings from one place.

The update also includes new visibility of "customer group inheritance", allowing you to see which rules are being used from another customer group. Head over to the new [Customer Groups area](https://app.sparklayer.io/customers/groups)!

**Improvements**

- **Price list improvements:**

  It's now possible to set up a price list to support a 100% discount against an automatic price source (e.g. your Shopify retail prices). This is useful if you have a requirement to allow specific B2B customers to purchase products at a zero-rated cost (e.g. $0.00)
- **My account credit limits now support multi-currency**

  If you're store is set up to allow multiple currencies for your B2B customers and you're using [credit limits and account balances](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md), you can now configure these specific to the customer's currency (e.g. GBP, EUR, USD)

## April 2024

**New features**

**Product Customisations**

If you sell products that require "customisations" such as custom text or any other unique requirements, you'll like our latest update! We've just released the ability to support customised products via the SparkLayer JavaScript SDK.

This allows your B2B customers to add customised text to products within their order and the information is sent through to your eCommerce platform when an order is placed.

![Product Customisations – Release archive](https://docs.sparklayer.io/images/shared/product-display-f2514f.webp)

> **Please note**
>
> This is an advanced configuration of SparkLayer and will require a developer to implement on a store that requires this feature. Please refer to our JavaScript SDK for full details.

**"Draft order" visibility in My Account**

We've just released a major improvement to the [My Account Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) that gives your B2B customers much better visibility on orders they place. Previously, if a customer placed an order via payment methods such as "Pay on Account" or "Pay by Invoice" these wouldn't show in the My Account until the order was marked as "Completed". Now, as soon as an order is placed, these will show with a new status "Awaiting Merchant".

!["Draft order" visibility in My Account – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/archive-fa8204.webp)

When you (the merchant) completes the order, these will then change to standard order statuses such as "Processing", "Shipped", etc. You can learn more about order status in [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md).

**Improvements**

- **Purchase numbers to support new order types**

  Inline with the "Draft order visibility in My Account" above, you can now set "Purchase numbers" to indicate orders that are currently in review. [Learn more about dashboard settings](https://docs.sparklayer.io/help/dashboard/settings.md)
- **Support for Shopify web pixels**

  SparkLayer now supports the new [Shopify web pixel tracking system](https://admin.shopify.com/settings/customer_events). This will in time replace the need to use the [SparkLayer checkout script](https://app.sparklayer.io/configuration/frontend/checkout) when implementing SparkLayer on Shopify.
- **Language support for Japanese**

  We've added Japanese as an option in our available [languages](https://docs.sparklayer.io/help/storefront/languages-and-international.md).

## March 2024

**New features**

**Company Order Approvals**

We're excited to announce a major update to our [Company Users](https://docs.sparklayer.io/help/customers/company-users.md) functionality: order approvals that let teams set role-based permissions!

![Company Order Approvals – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/archive-c4bc07.webp)

Via our [Company Users](https://docs.sparklayer.io/help/customers/company-users.md) feature, B2B customers can invite colleagues and set powerful role-based controls on what they can and can’t do (e.g. some can add items to an order, whereas others can complete the order to be fulfilled). _Please note, this feature will be launched later in March._

**Sales agent order history**

We've released a much requested improve to our [Sales Agent Ordering](https://docs.sparklayer.io/help/sales-ordering.md) feature. Sales Agents can now view recent order history pertaining to customer accounts they manage. When a sales agent logs in, they'll see this new section on the sales agent search interface.

![Sales agent order history – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/archive-4bfdbe.webp)

**Sales Agent - Setting overwrites**

It's now possible for Sales Agents (with "Administrator" access) to overwrite product settings such as pack sizing and min/max product quantities. When signed in as a customer, free form quantities can be entered to increment or decrement the line item level quantities. Learn more in [Sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md).

**My Cart - CSV file upload**

If your customers make use of the [CSV file upload feature](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md), they can now upload CSVs using a **barcode** as the primary identifier. This works in addition to use a SKU.

![My Cart - CSV file upload – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/archive-e919eb.webp)

**Improvements**

- **My Cart - show stock status**

  If you've configured SparkLayer to [show stock levels](https://docs.sparklayer.io/help/storefront/stock-display.md), the [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) will automatically show the stock status for any items added. It's a great way to give customers more visibility of the specific inventory levels of items in their order.
- **Product Card - Hide Prices**

  It's now possible to hide the total price from showing on the [Product Card Interface](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) if you'd prefer to keep this hidden. [Learn more about product display](https://docs.sparklayer.io/help/storefront/product-display.md)
- Product Stock - Hide inventory count

  If you have [Stock Display](https://docs.sparklayer.io/help/storefront/stock-display.md) turned on, you can now selectively hide the specific inventory count from showing. [Learn more about stock display](https://docs.sparklayer.io/help/storefront/stock-display.md)
- **Dashboard Price List - upload multiple CSV files**

  It's now possible to upload multiple CSV price lists at once when managing your B2B price lists. [Learn more.](https://docs.sparklayer.io/help/pricing/managing-pricing.md)
- **Cin7 Core integration - multi-currency**

  We've upgraded our Cin7 Core integration to now better support stores that have a multi-currency setup. Please contact our support team to learn more.
- **Loading interfaces**

  We've improved the loading interfaces that show when the [Frontend Interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) first load on a page, making for a smoother experience.

## February 2024

**New features**

**Dashboard usability improvements**

As part of our ongoing improvements to the [SparkLayer Dashboard](https://app.sparklayer.io/), we've released our first major update to make managing your B2B configurations even easier. For the [Price Lists](https://docs.sparklayer.io/help/pricing.md) and [Shipping](https://docs.sparklayer.io/help/ordering/shipping-rules.md) sections of the dashboard, you'll see a new and improved way to create and manage your settings with our new "slide out" feature.

In the very near future, we'll be rolling out a brand new [Customer Groups](https://docs.sparklayer.io/help/customers/customer-groups.md) section that will bring some major improvements to how you manage your B2B customers. Stay tuned!

**"Purchase status" improvements**

Under the hood, we've made some major improvements to how SparkLayer handles "purchases" (essentially orders that can have different statuses). This will allow SparkLayer to handle purchase types such as orders that may require review (e.g. a Draft order), orders that may require approval, and a range of other statuses that may be relevant to your B2B operation. In next month's update, we'll be sharing how this works and what it will unlock for our customers!

**Improvements**

- **Frontend interfaces - "Cart" terminology**

  We've updated the terminology for "Order" to "Cart" to make it more obvious to customers that products are added to a shopping list. This change will apply to any buttons and titles used in the [Frontend Interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md). This text can also be modified should you want to adjust to anything else. [Learn more about languages and custom text](https://docs.sparklayer.io/help/storefront/languages-and-international.md)
- **Frontend Interfaces - Notifications**

  We've improved the display of notifications within the frontend interfaces for actions such as "success", "information", and "warning" messages, ensuring a more consistent look and feel.

## January 2024

**New features**

**Purchase history reports**

Our headline update this month is the release of our new My Account reporting tool that gives your B2B customers even easier (and faster!) ways to place B2B orders!

The first report we've released is the new "Purchase history by time period" which gives customers a breakdown of all products they've purchased over a period of time (e.g. by quarter, by month, by week). The best part? In a matter of clicks, they can re-order an entire range of products and then proceed through the checkout to complete their order.

It's a great way to allow your customers to more rapidly repeat-order and easily see products they've purchased from your store. [Learn more about the My Account interface](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md)

**Custom payment method messaging**

On the final step of the [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md), Review & Pay, it's now possible to display a "custom payment messages" that let you add additional details about a payment method.

![Custom payment method messaging – Release archive](https://docs.sparklayer.io/images/shared/cart-and-checkout-455f26.webp)

For example, if a customer is paying by "Pay by Invoice", you could add some additional text to inform them on how this process works. [Learn more about cart and checkout options](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md)

**Improved messaging within the My Account and My Order**

When your B2B customers haven't completed certain actions (e.g. placed an order, saved a shopping list), we've improved the messaging and how this looks to give a more consistent feel and experience. You'll see the same style of "empty state" messaging appear in both the [My Account Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) and [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md).

![Improved messaging within the My Account and My Order – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/archive-ef2b35.webp)

**Improvements**

- **Sales Agents - "Recently Access Accounts"**

  When a sales agent logs in, they can now see their most recently accessed accounts, making it easier to login as a customer (this works based on their browser session).
- **Sales Agents - Search improvements**

  We've extended the sales agent customer search to now include additional data sources: the default billing postcode (Zip code), first line of address, and city
- **Sales Agents - Customers created by sales agents**

  When a sales agent now creates a new customer on the fly, this will automatically assign any "b2b" tags assigned to the sales agent themselves. This now makes it easier to filter and segment by sales agent created customers within Shopify or BigCommerce.
- **My Account - Order History "RRP" pricing**

  When viewing an order within the My Account area, if a product has [RRP pricing](https://docs.sparklayer.io/help/pricing/pricing-display.md) configured, you'll see this show next to the main B2B price.
- **Price Lists - support for 4 decimal places**

  When setting up an automatic price list (e.g. 50% off your retail prices), you can now specify up to 4 decimal places (e.g. 24.1245%)
- **Product Cards - selectively hide variant drop-downs**

  By default, the [Product Card Interface](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) will show any variants (such as colour and size) and allow the customer to change them. If you'd prefer, you can now hide specific variant groups you don't want to show, giving you more flexibility on what's shown to your customers. [Learn more about product display](https://docs.sparklayer.io/help/storefront/product-display.md)

## December 2023

**New features**

**Barcode support**

We're pleased to announce the launch of one of our most highly requested features, barcode support! If you're using barcodes within your eCommerce platform (e.g. Shopify), you can now display these to customers via our [Frontend Interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) and even allow customers to search by barcode in the [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md).

![Barcode support – Release archive](https://docs.sparklayer.io/images/shared/my-cart-3e9c40.webp)

You can also take this a step further and integrate SparkLayer with your barcode scanning system, to really automate the creation of B2B orders.

To learn more about activating barcodes, read [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md).

**Unit of measure pricing**

SparkLayer now supports the option to configure your pricing with **units of measure**, allowing you to offer discounted prices based on specific purchasing quantities.

It's a great way to allow customers to order in pre-defined units such as boxes, pallets, or cases. When setting these up, you can then specify how pricing works for these specific units, as well as handle units that 'fall outside' these. Learn more in [Quantity pricing & settings](https://docs.sparklayer.io/help/pricing/quantity-pricing.md)

**Improvements**

- **Quantity price display in the My Order widget**

  If you have [quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md) set up, customers can now see the details of how quantity pricing works directly from the [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md)
- **My Order CSV Import**

  You can now overwrite the default column headers in the CSV file import available to customers in the [My Account Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md). This allows you to overwrite the default `sku` and `qty` that is currently available. Learn more in [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md)
- **Product percentage savings**

  If you're using [quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md), you can now customise how the "Savings" column handles percentage savings with the option to add additional decimal places (e.g. 33.12% off instead of 33% off)
- **Messaging consistency**

  We've improved messaging within the [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) so that any actions that add items to an order (e.g. a CSV file import, a shopping list), the customer will be shown a notification message informing them if any products cannot be added

## November 2023

**New features**

**Custom shipping messages**

A common use-case we see with our customers is shipping rates needing updating after an order is placed. Perhaps you need to perform your own checks on the order or negotiate the final shipping cost. Our latest update to our shipping system allows you to set "custom messages" against shipping rules, allowing you to give more visibility to your B2B customers should the shipping costs need amending.

![Custom shipping messages – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/archive-ef81c3.webp)

You can learn more about how custom shipping messages work in [Shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md).

**Product Page "All Variants" Mode**

If your products come in multiple variant types (e.g. colour and size), you're going to like this update! You can now enable a special "All Variants" mode on the [Product Detail Interface](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) that allows your B2B customers to see all available variants in one go. Learn more in [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md).

**Order Limits by Quantity**

Alongside the ability to set [order total limits](https://docs.sparklayer.io/help/customers.md) for your B2B customers, you can now set **order quantity limits**! For example, you may require customers to have a minimum of 100 items in their order before they can checkout, or they cannot purchase more than 1,000 items.

![Order Limits by Quantity – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/archive-4ee9ff.webp)

Our latest update allows you to set order quantity limits for any of your [Customer Groups](https://docs.sparklayer.io/help/customers/customer-groups.md) and you can even combine order quantity and order total rules! [Learn more about customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md)

**Improvements**

- **CSV Import - messaging**

  We've improved the feedback messaging customers see if not all items in a [CSV file import](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) can be added to an order, allowing them to scroll the list of affected products if the list is very long
- **Price Lists - auto-assigning**

  If you're creating a price list for the first time, you can choose to 'auto-assign' the price list to your default B2B customer group
- **Product widgets - RRP text styling**

  You can now additional text styling to the [RRP price](https://docs.sparklayer.io/help/pricing/pricing-display.md) such as adding a strike-through or customising the colour. You can now use new CSS variables `--spark-pricing-rrp-decoration `and `--spark-pricing-rrp-color`

## October 2023

**New features**

**BigCommerce Integration**

It's here... the SparkLayer & [BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce.md) integration! Now BigCommerce merchants can integrate SparkLayer into their eCommerce stores and benefit from our feature-rich B2B solution. We're very excited to be part of the BigCommerce ecosystem and continue our mission to help brands grow their B2B businesses! Learn more in [BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce.md).

**Sales Agents Improvements**

We’re pleased to announce a range of major updates to our Sales Agent tool, that now makes it an even more powerful tool for B2B sales teams to use. And for merchants looking at levelling-up their B2B processes, it’s now even easier to onboard their sales team and bring more automation to their B2B processes. Let’s dive into the new features!

_1.Inline Price Editing_

Our built-in powerful B2B pricing engine lets customers see their exact B2B pricing rules when they login. However, what if a Sales Agent needs to make an ad-hoc change to a price or apply a discount to a range of products in one go? With our instant price editing feature, Sales Agents can now edit pricing “inline”, allowing them to edit prices in real-time before placing an order. Learn more in [Sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md)

_2. Create new customers_

This new feature lets Sales Agents rapidly add a new customer and begin placing orders for them right away. It’s particularly useful if a Sales Agent is on the road meeting new customers, or at a trade show needing to place orders there and then with a customer. Learn more in [Sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md)

_3. Place Sales Agent Orders_

Now, Sales Agents can not only add products to their personal orders but also complete the checkout process independently. Whether it's for buying a product for an upcoming customer demonstration or making a personal purchase at a preferential rate, this update now gives them the ability to do this!

> **Please note**
>
> The above [Sales Agent Ordering](https://docs.sparklayer.io/help/sales-ordering.md) updates are available to all customers on the Growth, Pro, and Enterprise plans.

**Improvements**

- **Product widgets - Dark Mode**

  We've extended the available design customisations for customers using the [dark mode](https://docs.sparklayer.io/help/storefront/customising-design.md) look and feel for the SparkLayer product page widgets
- **Shipping - Percentage of Net Total**

  You can now set shipping rates based on a percentage of the customer's order total, e.g. 20%
- **Dashboard - Team Invitations**

  We've made inviting team members easier with a new, streamlined process for becoming part of a team. [Learn more about account settings](https://docs.sparklayer.io/help/dashboard/account.md)
- **My Order - Product SKU search**

  We've updated the user interface for the SKU search on the [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) to display a new icon (a plus symbol instead of a search icon)
- **Error messages now have reference codes**

  If you ever encounter an error saying "Sorry, an unknown error has occurred", this will now include a reference code number. You can see the list of common error codes in [Troubleshooting](https://docs.sparklayer.io/help/troubleshooting.md)/

## September 2023

**New features**

**Shopify Onboarding Dashboard**

If you're using your Shopify admin to keep tabs of your SparkLayer installation process, you'll like our latest update!

We've now greatly improved the interface, making it easier to see the key onboarding steps, learn about available features, and quickly access the main [SparkLayer Dashboard](https://app.sparklayer.io/) to complete your onboarding process.

**Restricting billing address modifications**

By default, you can allow customers to [edit and manage addresses](https://docs.sparklayer.io/help/customers/account-and-addresses.md) via their My Account area. If you'd prefer to restrict them from editing their billing address, you can now enable this via the [Configurations area](https://app.sparklayer.io/configuration/settings/general) of the SparkLayer Dashboard.

![Restricting billing address modifications – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/archive-eb4ee4.webp)

**Improvements**

- **Product widgets - single variant products**

  If you have single variant products on your website, you can now display the full variant name in the [table-view mode](https://docs.sparklayer.io/help/storefront/product-display.md)
- **CSS styling controls**

  We've now added the ability to customise the "Order Complete" checkmark icon colour that shows to customers once an order is placed
- **Price Lists admin**

  If you now try to download a "manual price list" that hasn't had prices uploaded, you'll be prompted with a message (rather than downloading a blank file previously)

## August 2023

**New features**

**Checkout address editing**

We're pleased to announce one of our most requested features - checkout address editing! Customers can now add new addresses directly from the [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md), making it even faster to choose shipping addresses and complete an order

This new feature can also help streamline and compliment any drop-shipping activities your customers may be doing. To learn more about how it works, see [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md).

**Set minimum and maximum order limits**

To add more flexibility to your ordering rules, we've now released the ability to set both minimum and maximum order requirements for your customer groups.

Based on the rules you set, you can now more easily restrict customers from being able to checkout until they meet the order requirements. To learn more, see [Customers](https://docs.sparklayer.io/help/customers.md).

**Custom checkout message**

On the final step of the [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md), Review & Pay, it's now possible to display a "custom checkout message" that lets you inform customers of any special notes or information they need to be aware of.

![Custom checkout message – Release archive](https://docs.sparklayer.io/images/shared/cart-and-checkout-4650c1.webp)

It's a great way to highlight information about shipping, payment, or anything else! [Learn more about cart and checkout options](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md).

**Improvements**

- **My Order - displaying RRP price**

  If you've set up [rrp pricing](https://docs.sparklayer.io/help/pricing/pricing-display.md) for your products, you can now display the RRP price within the [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md)
- **My Order - selecting a payment method**

  If a customer has pre-selected a payment method (e.g. Pay by Invoice) and subsequently makes changes to their order, the payment method will now be pre-selected (rather than resetting back to the default payment method)
- **Product widgets - handling for "Unavailable"**

  If all variants of a product are set as "Unavailable" (i.e. they have no B2B pricing set), the [Product Detail Interface](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) and [Product Card Interface](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) will now hide the "Add to Order" button from showing to a customer
- **Product cards - improved handling for variants**

  If your products have multiple levels of variants (e.g. colour and size), the [Product Card Interface](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) will now only show available variants based on availability and "disable" variants that cannot be added to an order
- **My Account - "Financials" section**

  If you have [credit terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) set up for your B2B customers but you'd prefer to hide the "Financials" section from the [My Account Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md), you can now do this via a new configuration. [Learn more about the My Account interface](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md)
- **Dashboard - Shipping**

  You can now more easily edit and delete shipping rules directly from the [Shipping](https://docs.sparklayer.io/help/ordering/shipping-rules.md) area of the SparkLayer Dashboard

## July 2023

**New features**

**Display custom fields within the My Account**

Within the [My Account Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md), it's now possible to show "custom fields" allowing you to add additional information that you want your B2B customers to see. For example, you may want to include details of their sale agent contact, website address, or anything else!

![Display custom fields within the My Account – Release archive](https://docs.sparklayer.io/images/shared/my-accountarea-5631ae.webp)

Setting custom fields for the My Details area works in a very similar way to the [custom checkout fields feature](https://docs.sparklayer.io/help/ordering/checkout-fields.md) and you can learn more in our [Account & addresses](https://docs.sparklayer.io/help/customers/account-and-addresses.md).

**Upload invoices to an order**

When viewing an order, in addition to the order details (such as products ordered, order status, address), it's now possible to attach an invoice against an order that the customer can subsequently download.

![Upload invoices to an order – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/order-3fd566.webp)

Once the invoice has been uploaded, your customers can then view the invoice by viewing their order details within the [My Account Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md).

![Upload invoices to an order – Release archive](https://docs.sparklayer.io/images/shared/quickbooks-0dd422.webp)

You can learn more about how to set this up in [Credit, net terms & invoicing](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md).

**Improvements**

- **Price lists - clearing prices**

  You can now "clear" price lists within the [SparkLayer Dashboard ](https://app.sparklayer.io/pricing)for any price lists that you've manually uploaded (via a CSV). This is especially useful if you want to remove existing price list data and re-upload it.
- **My Order - uploading CSV data**

  Within the [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md), you can now paste in CSV data to quickly populate an order. This works alongside the existing CSV file upload feature. Learn more in [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md).
- **Product cards - display stock level and SKU**

  Within the [Product Card Interface](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md), you can now optionally display a live stock level and SKU (product code). [Learn more about product display](https://docs.sparklayer.io/help/storefront/product-display.md)
- **Checkout validation**

  You can now define more granular rules for validating whether a customer is allowed to proceed to checkout. Learn more in out JavaScript SDK.

## June 2023

**New features**

**Integration with experience platform, Pack**

![Integration with experience platform, Pack – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/article-pack-794709.webp)

Speed and performance have always been at the heart of how we’ve built SparkLayer: from how we manage the complexities of B2B pricing in a scalable way, through to ensuring that the end B2B customer gets the smoothest possible experience when placing orders online.Today, we're thrilled to announce our latest partnership that takes this a step further, as we launch our official integration with Pack! [Learn more about](https://www.sparklayer.io/blog/2023/05/18/sparklayer-pack-headless-shopify-b2b/) our partnership.

**Configure net payment terms more easily**

We've just made setting customer net payment terms even easier! If you're using the SparkLayer "Pay on Account" payment method, you can now set up specific net payment terms for a customer and have this automatically populate the payment terms in Shopify.

![Configure net payment terms more easily – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/2023-05-20-08-38-15-311953.webp)

**Improvements**

- **Address book - phone numbers**

  When adding an address in the My Account area, you can now optionally make customers specify a phone number. This will then be included in the customer's details if they proceed to place an order
- **Address book - billing & shipping address**

  When adding an address in the My Account area, customers can now specify if they want the address to be their default Billing and/or default Shipping address. This is useful if they require different addresses when placing an order

## May 2023

**New features**

**The new B2B Price Engine**

![The new B2B Price Engine – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/article-92a406.webp)

We’re excited to announce the launch of one of our most anticipated updates, our new Price Engine that gives SparkLayer customers powerful new ways to automate and streamline their B2B pricing rules!

![The new B2B Price Engine – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/price-list-bfee2b.webp)

Previously, SparkLayer gave customers the ability to manage pricing via CSV uploads and, for more complex integrations, automating pricing via the SparkLayer API. With the new Price Engine, SparkLayer customers can now:

- Use pricing from their eCommerce platform (e.g. Shopify) to create automatic B2B pricing (e.g. set B2B prices to be 20% off Shopify prices)
- Set up automatic pricing based off other price lists (e.g. 50% off your default price list)
- Quickly download price lists to make edits and then easily re-upload
- Edit pricing “inline" with our Price Editor Tool
- Import manual prices more quickly, with a major performance boost

Learn more in our [recent announcement](https://www.sparklayer.io/blog/2023/04/17/b2b-pricing-system/) or see how it works in [Pricing](https://docs.sparklayer.io/help/pricing.md).

**Improvements**

- **Product widgets**

  You can now optionally display the RRP prices anywhere on your storefront with our new RRP price widget
- **Performance improvements**

  We've made a range of improvements under the hood to speed up the process of importing pricing into SparkLayer

## April 2023

**New features**

**The new Price Editor**

The **Price Editor** tool compliments the pricing import tool, allowing you to easily add and edit pricing in a more "ad hoc" manner. For example, perhaps you need to edit a single price for product and add a new one, and you'd prefer not to upload a new CSV file to do this.

![The new Price Editor – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/2023-04-03-08-32-12-2d4711.webp)

The Price Editor tool works by letting you search for a product SKU and then edit and add pricing inline, allowing you to rapid modify your B2B pricing. Our team has been busily working on our major pricing engine update (coming soon!) and we've also released the following improvements.

**Improvements**

- **Languages**

  We've added support for Hebrew and Georgian to the SparkLayer Frontend. See all languages we support.
- **SDK updates**

  If you're using our JavaScript SDK to build more custom interfaces, you can now reference the total weight of an order. This is useful if you want to hide/show messaging based on a customer's order contents reaching a certain weight threshold.
- **Performance improvements**

  We've made a range of improvements under the hood to speed up the process of importing pricing into SparkLayer

## March 2023

**New features**

**Checkout Custom Fields**

Checkout Custom Fields give you the ability to capture additional information from the customer when they checkout. We've released two enhancements that give even more flexibility to how you set these up as well as new ways to display this data to customers.

![Checkout Custom Fields – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/archive-ebbc4e.webp)

It's now possible to set validation rules within Checkout Custom Fields allowing you to apply restrictions to fields such as dates (for example, blocking customers from selecting a weekend).

![Checkout Custom Fields – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/archive-43a5f7.webp)

**Improvements**

- **Data Sync area**

  We've released a new area to the SparkLayer Dashboard called Data Sync that combines both product and customer data sent from Shopify.
- **Payment methods**

  It's now possible to change the order that payment methods show during the checkout as well as set the default.
- **Stock level key**

  You can now display the stock level key on desktop by using the CSS variable

  `--spark-pdp-stock-key-desktop: flex`
- **Cart notification**

  You can optionally hide the progress bar by using the CSS variable

  `--spark-toast-animation-display: none`

## February 2023

**New features**

**Company Users**

It's here! One of our most anticipated product updates, Company Users, is now available! Company Users is a brand new tool that’s designed to improve the B2B purchasing and account management flow within an organisation. Sometimes referred to as "B2B account management", it allows companies to create teams of users (i.e. _Company Users_) that can share specific actions within their account.

![Company Users – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/article-b2b-company-users-21ad3e.webp)

From placing orders and tracking their status, repeat ordering previous orders, through to creating shopping lists and sharing address books. What sets the SparkLayer Company Users tool apart is how simple it is to use. Inline with our approach to make the B2B experience self-service, customers themselves can create their own teams right from within their My Account area. There’s no need to request the store owner to manage this on their behalf, the customers themselves have full control over the process. Learn more about Company Users.

**Improvements**

- **Multi-currency support**

  We've made some major improvements to how SparkLayer works with Shopify Markets/multi-currency meaning you can manage this all within a single Shopify store.
- **My Account Re-ordering**

  When viewing a completed order in the My Account area, it's now possible to re-order items on a product-by-product basis.
- **The SparkLayer Dashboard**

  We've made a number of interface improvements including the ability to edit and delete customer groups.

## January 2023

**New features**

**DEAR Systems Integration**

We’re pleased to release our latest integration with DEAR Systems. DEAR Systems has long held the reputation as being the system of choice for established and fast-growing brands, providing a centralised location to manage inventory, orders, warehousing, fulfilment, accounting, and more.

![DEAR Systems Integration – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/dear-b031dd.webp)

The SparkLayer integration works by connecting to the merchant's DEAR Systems account to access B2B data such as product pricing and price lists as well as synchronising B2B customer data.

**Improvements**

- **SparkLayer Quick Order**

  Customers will now see a running total of ‘lines’ and ‘items’ next to the sub-total. This makes it easier for them to see the size of their B2B order
- **Dark mode**

  For merchants using a ‘dark’ theme, we’ve Improved support for dark mode on collection pages
- Right-to-Left mode: SparkLayer now supports countries/languages that require “right-to-left” (or RTL)
- **Language editing**

  We’ve made it easier to manage language updates with a simpler way to add text overwrites within your storefront
- **Language translation support**

  We’ve added support for Romanian and Arabic.

## December 2022

**New features**

**1-click Shopify B2B theme install**

If you're using SparkLayer on Shopify, you may be aware of Shopify's latest theme, [Dawn](https://themes.shopify.com/themes/dawn/styles/default). With our new 1-click B2B theme install, any merchant using SparkLayer can now _instantly_ install our B2B-optimised version of the Shopify Dawn theme and get up and running with their B2B store in a matter of minutes. Best of all, **no code changes are required** to set this up.

![1-click Shopify B2B theme install – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/archive-9986ba.webp)

It's a great way to test how SparkLayer works before installing it on a live Shopify theme or you could even use it as the basis for your next B2B store! To get started, go to the [SparkLayer Dashboard](https://app.sparklayer.io/configuration/frontend/core).

**Improvements**

- **Product page widget**

  The product page widget currently shows a special 'table' view for products that have variants (e.g. size, colour). You can now render the same 'table' view for single variant products by adapting the product widget code.
- **Product settings**

  We've updated our documentation on product settings including how it's possible to set products (and variants) to not be "sellable" to B2B customers and even how to fully hide products (and variants) from showing with a special "display" setting.
- **Tiered pricing**

  By default, if you have tiered pricing set up, the pricing will be applied across all variants of a product. You can now set this to only apply to specific variants via a new setting within the SparkLayer Dashboard.
- **Pack sizing**

  The product detail page widget now supports a 'Pack price' that gives customers a cost for all products within a pack.
- **Product widgets customisations**

  We've enabled additional design customisation settings including button and input styling.
- **Line item limits**

  With Shopify's line item limit of \~ 250 items, we've now included special notifications within the SparkLayer Quick Order if customers exceed this limit
- **Dashboard product data**

  You can now search by SKU within the Data look up tool in the SparkLayer Dashboard.
- **Brightpearl integration**

  We've made improvements to the handling of customer address syncing for BrightPearl, including phone numbers and company names.

## November 2022

**New features**

**Configure "custom dates" for backorder products**

With support already for backordering/pre-ordering built into SparkLayer, we’re excited to announce our latest update, "custom dates" that can be set for backorder products."Custom dates" allow you to set an exact date when the product is expected to be available. It’s a great way to give the end customer better visibility of when to expect receipt of the products on order, and helps deliver an overall better customer experience.

![Configure "custom dates" for backorder products – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/backorder-due-date-pdp-3bb9c4.webp)

Use-cases could include:

- Setting a "due in" date of when you're expecting the product to be in stock
- Setting an "estimated shipping" date of when you're expecting the product to ship

**Improvements**

- **Product page tiered pricing**

  If you're using tiered pricing, the information table shown to customers on a product page will now include pack sizing. For example, if your tiered pricing starts at 6 units, this will be shown as the first in the list.
- **Product page widget**

  We've improved the interface of the product page widget to hide the initial variant dropdown if a product only has a single option within it.
- **Product card variants**

  If a product has variants that don't have prices assigned, these will be shown last in the purchasing dropdown on the product card widget
- **My account area**

  If you're using our account balance feature, you can now optionally hide any reference to 'credit' if you don't set a credit limit against a customer.
- **CSV import**

  The SparkLayer Quick Order Interface now has improved messaging for customers using the CSV import tool, making it clearer when a product isn't able to be imported due to stock limitations.

## October 2022

**New features**

**Custom Fields during the checkout**

Our latest update includes the much anticipated 'custom fields' feature that allows you to add **additional** data capture fields during the checkout process.

![Custom Fields during the checkout – Release archive](https://docs.sparklayer.io/images/shared/cart-and-checkout-2c7bcf.webp)

Use-cases could include:

- A date capture field, e.g. "Shipping" or "Delivery" date
- Purchase order number (PO number)
- Additional Shipping requests

Custom fields has support for the following types of data capture: Text entry fields, Select menus (i.e. drop downs), Date selection, Email, Phone, and more.

**Improvements**

- **Price lists deletion**

  You can now delete price lists directly from the SparkLayer price list admin
- **Total quantity of items**

  The SparkLayer Quick Order Interface will now show the total units in a customer's order (i.e. total quantity) before checking out
- **Customer credit and payment on account**

  If you have customer credit enabled, you can now allow customers to optionally be able to checkout using Payment on Account (previously this was blocked for customers who exceed their credit limit)
- **We've partnered with Balance payments** to offer Buy Now and Pay Later for B2B merchants using Shopify. Learn more

## September 2022

**New features**

**Quick Buy Mode**

Our new Quick Buy Mode gives you a new way to display the SparkLayer product widget on your collection pages with an optimised 'table' view.

![Quick Buy Mode – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/archive-ed2f8a.webp)

**Improvements**

- **Back-order, minimum stock level**

  If you're using the backorder feature, it's now possible to set granular minimum stock levels at a product variant level giving you more flexibility on how many units you allow to be sold to customers.
- **Product variant images**

  If you've product images within Shopify that are assigned to a product variant (e.g. colour), it's now possible to change the images shown to a customer when a variant is selected via SparkLayer. This is a manual change, if you would like this enabled please contact us
- **Cart line item limit**

  We've increased the maximum line items available in a single order from 100 to 250, with customer-friendly messaging should customers exceed this.

  Languages: we've added support for new languages, Norwegian and Finnish

## August 2022

**New features**

**B2B shipping rules**

If you've set up SparkLayer on your B2C (DTC) website and need to create different shipping rules for your B2B customers, you can now do this via the SparkLayer shipping tool.

![B2B shipping rules – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/archive-082b30.webp)

**Improvements**

- **Address display**

  We've improved visibility of shipping addresses and customers can now see their selected address just before they complete their order. The address summary will show in the final order totals section of the SparkLayer Quick Order Interface
- **CSV importing**

  We've made improvements to our CSV import tools, with handling for different currency formats. For customers uploading price lists in Euros for example, the import will now support comma formats for pricing (such as 19,99)
- **Performance**

  We've released a big performance improvement to the frontend, with a more rapid login process. We've re-engineered how our user authentication works and merchants should now see a much quicker log in process when a B2B customer signs in.

## July 2022

**New features**

**Show product settings**

If you've configured your products to work with settings such as pack sizing or minimum and maximum quantities, you can now display this to customers anywhere where you show the SparkLayer product interface. Once enabled, this will show a new 'Qty rules apply' message that will show all associated product rules you've set up.

![Show product settings – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/archive-59e243.webp)

![Show product settings – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/archive-59002d.webp)

**Show order notes from My account overview**

If customers place an order and include a special note (e.g. PO number), this can now be viewed from the My account overview page

![Show order notes from My account overview – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/archive-725bf2.webp)

**Improvements**

- **Shopping list names**

  If a customer creates a new shopping list and uses the same name as an existing one, this will now fully overwrite it instead of creating a duplicate
- **My account ship-to address**

  You can now show the shipping address for an order from the My account overview page.

## June 2022

**New features**

**Show tiered pricing on product cards**

If you're using tiered pricing, you can now display the discount summary within the product card widget. The product card will now _optionally_ display the cheapest price to the customer as well as the maximum discount they could receive. The customer can also mouse-over the widget to see a fully summary of the tiered pricing available. You can test out how it works [on our demo store](https://shopify-demo.sparklayer.io/pages/b2b-login-register)

![Show tiered pricing on product cards – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/archive-0a3f73.webp)

**My Account order tracking information**

If you supply shipping information against a customer's order within Shopify, this will now be shown within the SparkLayer My Account interface when viewing an order. The tracking information includes

- A link to the shipping company's own tracking page
- The specific tracking number for the customer's visibility

![My Account order tracking information – Release archive](https://docs.sparklayer.io/images/help/whats-new/archive/archive-3386a5.webp)

**Improvements**

- **Address searching**

  If B2B customers have large numbers of addresses saved against their address book, they can now use a special search box to more easily select their preferred address.
- **Multi-currency support**

  For merchants using a custom ERP solution, we can now enable multi-currency on the same Shopify instance. This is currently restricted only to manual payments only (e.g. Payment by Invoice, Request for Quote) and does require technical investigation before enabling.
- **JavaScript SDK**

  For merchants using our SKD, we've added some additional events including 'on cart update'.


---

# Get started

URL: https://docs.sparklayer.io/help/get-started

Set up SparkLayer with the five-step Setup checklist: create a price list, assign it to a customer group, invite a buyer, then add SparkLayer to your theme.

> **Quick summary**
>
> - Setup is 5 steps on the **Setup** checklist at **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app: 3 in SparkLayer (a price list, a customer group and your first buyer) and 2 for your theme. Most stores finish in under 15 minutes.
> - Want to see SparkLayer as a buyer first? [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order) places a test order on your own store that doesn't count towards your plan.
> - The Setup checklist is built around Shopify. On BigCommerce, Wix, WooCommerce or Magento, start with your platform's install guide: see [Other platforms](#other-platforms).

If price lists and customer groups are new to you, read [How SparkLayer works](https://docs.sparklayer.io/help/get-started/how-sparklayer-works.md) first. It explains the ideas these steps rely on in a few minutes.

Not sure where to start? Answer 4 quick questions and get [your own setup guide](https://docs.sparklayer.io/help/get-started/setup-guide.md): the guides that apply to your store, in the order you need them.

## Before you start

- **SparkLayer installed on your store.** On Shopify, install the **SparkLayer Wholesale** app: see [Install SparkLayer on Shopify](https://docs.sparklayer.io/help/platforms/shopify/install.md). On other platforms, see [Other platforms](#other-platforms).
- **Your B2B prices, or the rule for them**, for example 20% off your retail prices. A spreadsheet of prices by SKU is fine.
- **An email address for your first buyer**: a real trade customer, or an address of your own to test with.

## How setup works

The 5 Setup steps:

1. **1. Price list**: The prices your B2B customers see
2. **2. Customer group**: Decides which buyers see that price list
3. **3. First buyer**: Added, and sees trade prices when they sign in
4. **4. Theme**: SparkLayer added to your theme
5. **5. Publish**: The theme is live for your customers

The **Setup** page lists the steps in 2 groups: **SparkLayer setup** (steps 1 to 3) and **Theme setup** (steps 4 and 5, for your Shopify theme). Each step shows **Complete** or **To do**, based on your store's data. A step ticks itself off once it's done, however you did it.

| Version | Where to find Setup |
| --- | --- |
| **Shopify app** | **Setup**, in the menu under **SparkLayer Wholesale** in your Shopify admin. |
| **SparkLayer Dashboard** | On **Home**, click **Open Setup** on the **Get your first wholesale order** card. There's no Setup item in the menu. |

**The setup card on Home**

Until your first order comes in, **Home** shows a **Get your first wholesale order** card. It has the same 5 steps, a progress bar and a **Next** box with the next step's button. After your first order, the card becomes **Get live with SparkLayer** until every step is complete. You can minimise or dismiss the card. The steps are always on the Setup page.

## Work through the steps

### Step 1. Set up a price list

Price lists set the prices your B2B customers see. On the step, click **Create a price list**.

**More detail**

You can also 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**. A price list can be worked out from your retail prices (for example, 20% off), uploaded as exact prices by CSV, or sent from another system. The free Basic plan includes 3 price lists. See [Managing pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md).

### Step 2. Assign a price list to a customer group

Customer groups decide which price list a buyer sees when they sign in. Click **Open customer groups**, open a group and choose its **Price list**.

**More detail**

Customer groups are at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app. Every store starts with a **Base customer group**, whose settings every B2B customer gets. That's enough to get going. Create more groups when some buyers need different prices, payment methods or a minimum order. See [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md).

### Step 3. Add your first buyer

Click 

**Invite a buyer**

, enter their email, choose a 

**Customer group**

 and click 

**Send invite**

. They see your trade prices as soon as they sign in.

The step completes once any customer group has customers. To add them yourself, tag them `b2b` in your Shopify admin (see [Add B2B customers on Shopify](https://docs.sparklayer.io/help/platforms/shopify/invite-customers.md)), or approve a registration form entry in [Forms](https://docs.sparklayer.io/help/forms.md).

**More detail**

The invite adds the buyer to your store with the group's tag, such as `b2b-trade`. In the Shopify app, Shopify emails them an invite and they sign in with a one-time code. In the SparkLayer Dashboard, SparkLayer sends its own invite with a **Create trade account** button. To share a sign-up link instead, click **Copy registration link**. See [Invite a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md).

### Step 4. Add SparkLayer to your theme

SparkLayer adds its B2B pricing, cart and account area to your Shopify theme. On most themes, this is set up for you. Click **Review theme setup** to check each block. On other platforms, add the widgets as your platform guide describes: see [Other platforms](#other-platforms).

**More detail**

**Shopify only:**

The theme steps apply to the theme chosen under **Select theme**. Your published theme is marked **Active**. [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md) shows which SparkLayer blocks are on, and opens the theme editor at any of them. If something isn't right, our team installs SparkLayer for you, free. Click **Something not right? Install SparkLayer for me** there, or **Request installation** at **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app.

### Step 5. Publish your theme

Publish the theme you set SparkLayer up on. The step completes when that theme is published and active for your customers.

**More detail**

**Shopify only:**

If you set SparkLayer up on a copy of your theme, publish that copy in your Shopify admin at **Online Store > Themes** ([open in the Shopify admin](https://admin.shopify.com/themes)).

When all 5 steps are complete, Setup shows **You're ready to go with SparkLayer**. Next, place a test order with [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order), then work through the [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md).

> **We can set it up with you**
>
> On every plan, our team installs the storefront widgets for you, free, usually within days. On a paid plan, an onboarding session can also set up your first price lists with you. Click **Book setup call** at the top of Setup, or **Book free setup** on Home. To message our team, click **Chat with support** at the top of Setup. See [Contact support](https://docs.sparklayer.io/help/support.md).

## Other platforms

On BigCommerce, Wix, WooCommerce and Magento, setup follows the same idea in a different order. The Setup checklist in the SparkLayer Dashboard is only for Shopify stores.

1. **Install SparkLayer** and connect your store with your platform's guide: [BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce/install.md), [Wix](https://docs.sparklayer.io/help/platforms/wix/install.md), [WooCommerce](https://docs.sparklayer.io/help/platforms/woocommerce/install.md) or [Magento](https://docs.sparklayer.io/help/platforms/magento/install.md).
2. **Set up a price list** 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, as in [step 1](#set-up-your-b2b-pricing).
3. **Assign it to a customer group** at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app, as in [step 2](#set-up-your-customer-groups).
4. **Mark your B2B customers** in your platform: a BigCommerce customer group whose name starts with `B2B`, the `b2b` label on Wix, a **SparkLayer B2B** role on WooCommerce, or a **B2B:** customer group on Magento. See [Customer groups](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group).
5. **Add the widgets** to your theme as your platform guide describes. Our team can do it for you, free: see [Request free installation](https://docs.sparklayer.io/help/support.md#request-free-installation).
6. **Test, then launch** with the [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md).

## Optional: connect your other systems

You don't need this to get started. On the Pro plan, you can send price lists, customer rules and product data, such as pack sizes, from an ERP, CRM or other system. This is usually a job for your developer or integration partner, using the [SparkLayer API](https://docs.sparklayer.io/developers/api.md). Create an API key at **Settings > API** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/api)), or **SparkLayer Wholesale > Settings > API** in the Shopify app, or use a ready-made [integration](https://docs.sparklayer.io/help/integrations.md).

## Next steps

- [Try our demo](https://docs.sparklayer.io/help/get-started/demo.md): See SparkLayer as a B2B buyer on our demo store, with nothing to set up
- [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md): Test, invite your first customers and go live
- [Contact support](https://docs.sparklayer.io/help/support.md): Book a setup call or contact our team


---

# Your setup guide

URL: https://docs.sparklayer.io/help/get-started/setup-guide

Answer 4 quick questions about your store and get a setup guide made for you: the SparkLayer guides you need, in order, to tick off as you go.

> **Quick summary**
>
> - Answer 4 quick questions about your store, prices, customers and systems. It takes about a minute.
> - You get your own step-by-step setup guide, with only the guides that apply to you, in the order you'll need them.
> - Tick each step off as you go. Your answers and progress are saved in this browser, so your guide is here when you come back.
> - On a paid plan, bring it to your onboarding call: the guide ends with ideas for what to cover.

Rather than reading every guide, tell us what you need and we'll pick the ones that matter for your store. New to B2B pricing? Start with [How SparkLayer works](https://docs.sparklayer.io/help/get-started/how-sparklayer-works.md), which explains the ideas your guide builds on.

The page builds a personal setup guide from 4 short questions. On the page, answer them and you get your own step-by-step guide through these docs, which you tick off as you go. Your answers and progress are saved in your browser.

1. **Your store:** your platform, where you're starting from (new to B2B, phone and email orders, another B2B app or Shopify B2B), and who's setting SparkLayer up.
2. **Your prices:** how you set B2B prices (a rule, a spreadsheet or your ERP), who gets which prices, and whether you need quantity breaks, discounts or RRPs.
3. **Customers and ordering:** how customers pay, ordering rules (minimum orders, pack sizes, credit limits, stock levels), and whether you have sales reps, company accounts, online applications or wholesale hidden from retail.
4. **Systems and finishing touches:** the ERP or accounting systems to connect, and extras such as checkout fields, B2B shipping, branding and languages.

The guide always covers the basics, connecting your store, prices, customers and ordering, and testing and launch. For the full checklist without the quiz, see [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md).

## Prefer a checklist?

The [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md) covers testing, inviting your first customers and going live, for every store. Our team can also help you set up: we install the storefront widgets for you, free, and on a paid plan you can [book an onboarding call](https://book.sparklayer.io/). See [Contact support](https://docs.sparklayer.io/help/support.md).


---

# How SparkLayer works

URL: https://docs.sparklayer.io/help/get-started/how-sparklayer-works

How SparkLayer adds B2B ordering to your store, from data sync to orders, and the key ideas it's built on: price lists, customer groups, widgets and more.

> **Quick summary**
>
> - SparkLayer adds B2B ordering to the store you already have. Products, customers and orders stay in your eCommerce platform, and SparkLayer syncs the data it needs.
> - You set the B2B rules in SparkLayer: **price lists** hold prices, and **customer groups** decide which prices, payment methods and ordering rules each customer gets. You can also send them from another system.
> - When a B2B customer signs in, SparkLayer's **frontend interfaces** (widgets) show them their prices, cart and account on your store. Their orders arrive in your store's admin like any other order.
> - New to B2B? [Key concepts](#key-concepts) explains each idea in plain English. Then build [your setup guide](https://docs.sparklayer.io/help/get-started/setup-guide.md): the steps for your store, in order.

## How it works in 5 steps

SparkLayer sits alongside your store. Here's what happens, from connecting your store to fulfilling an order:

1. **SparkLayer connects to your store.** It links to your eCommerce platform, such as [Shopify](https://docs.sparklayer.io/help/platforms/shopify.md), and syncs product and customer information.
2. **You set your B2B rules.** Create [price lists](#price-lists) and set rules for each [customer group](#customer-groups), such as which payment methods they can use. Manage them in [the app](#the-sparklayer-app). You can also automate them from an ERP or CRM with the [SparkLayer API](https://docs.sparklayer.io/developers/api.md).
3. **Customers order on your website.** SparkLayer's [frontend interfaces](#frontend-interfaces) give signed-in B2B customers self-service ordering: their prices, quick ordering, re-ordering and an account area. Retail customers see your store as normal.
4. **Your sales team can help.** With [sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md), your team manages B2B accounts and orders for customers. The [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md) covers the full quote-to-order process.
5. **Orders arrive in your admin.** B2B orders are created in your platform's admin. You review, edit and fulfil them with the processes you already use. SparkLayer's [Orders](https://docs.sparklayer.io/help/dashboard/orders.md) page shows your B2B sales over time.

## When a B2B customer signs in

SparkLayer matches them to a customer group by their tags, and applies that group's rules to everything they see and order.

What happens when a B2B customer signs in:

1. **B2B customer**: Signs in to your store
2. **Customer group**: Matched by their tags
3. **Rules**: Price lists, payment methods, order limits
4. **Storefront**: Their prices, cart and checkout
5. **Order**: Created in your platform

## Key concepts

The ideas SparkLayer is built on, grouped by area. Jump to one, or read on: each takes a minute.

- **[Your store](#your-store-and-sparklayer)**: Where SparkLayer runs and how you manage it. [Your platform](#your-ecommerce-platform), [SKUs](#products-and-skus), [Data sync](#data-sync), [The app](#the-sparklayer-app).
- **[Pricing](#pricing)**: The B2B prices each customer sees. [Price lists](#price-lists), [Quantity pricing](#quantity-pricing-and-discounts).
- **[Customers](#customers)**: Who your B2B buyers are and their rules. [B2B customers](#b2b-customers), [Customer groups](#customer-groups), [Companies](#companies-and-company-users), [Sales agents](#sales-agents).
- **[The storefront](#the-storefront)**: What buyers see and use on your website. [Widgets](#frontend-interfaces), [Checkout and payment](#checkout-and-payment).
- **[Going live](#going-live)**: Testing safely, and what your plan includes. [Testing](#testing), [Plans](#plans).

## Your store and SparkLayer

### Your eCommerce platform

SparkLayer runs on top of your store on [Shopify, BigCommerce, Wix, WooCommerce or Magento](https://docs.sparklayer.io/help/platforms.md). You keep managing products, stock, customers and fulfilment there. SparkLayer adds the B2B layer: trade pricing, B2B ordering rules and self-service ordering.

### Products and SKUs

SparkLayer matches B2B prices to your products by SKU (stock keeping unit). That's the product code you set on each product and variant in your platform. Every product you want B2B customers to buy needs a SKU, and each SKU must be unique. See [Check your products have unique SKUs](https://docs.sparklayer.io/help/get-started/launching.md#check-your-products-have-unique-skus).

### Data sync

SparkLayer keeps a copy of the product and customer data it needs. It updates the copy automatically when you change something in your platform. If a product doesn't look right in SparkLayer, look it up at **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app. Customers that didn't sync show in a banner at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app. See [Monitoring data sync](https://docs.sparklayer.io/help/integrations/data-sync.md).

### The SparkLayer app

You set up and manage everything in the SparkLayer app: price lists, customer groups, orders and settings. It comes in 3 versions with the same screens.

| Version | Where | How it's laid out |
| --- | --- | --- |
| **SparkLayer Dashboard** | [app.sparklayer.io](https://app.sparklayer.io/), on any platform | A sidebar with grouped pages, such as **Pricing > Price lists**. |
| **Shopify app** | **SparkLayer Wholesale**, under **Sales channels** in your Shopify admin | One menu item per area, with that area's pages as tabs. |
| **Wix app** | **SparkLayer B2B & Wholesale**, under **Apps** in your Wix dashboard | The same screens, inside Wix. |

The Help Center shows the path for the version you use. See [Find your way around SparkLayer](https://docs.sparklayer.io/help/dashboard.md).

## Pricing

### Price lists

A [price list](https://docs.sparklayer.io/help/pricing.md) is a set of B2B prices for your products, keyed by SKU. A price list can be:

| Type | How prices are set |
| --- | --- |
| **Automatic** | Calculated from another price source, such as your store's retail prices, with a percentage change (for example, 40% off). |
| **Manual** | Uploaded as exact prices by CSV, or edited in the [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md). |
| **Integration** | Sent from another system, such as an ERP, through the [SparkLayer API](https://docs.sparklayer.io/developers/api.md). |

You can combine them, for example an automatic price list with exact prices uploaded for a few products. Prices are shown excluding tax, and tax is added at checkout.

### Quantity pricing and discounts

On top of price lists, you can set [quantity breaks and pack sizes](https://docs.sparklayer.io/help/pricing/quantity-pricing.md) and [discounts](https://docs.sparklayer.io/help/pricing/discounts.md) for B2B customers.

## Customers

### B2B customers

A B2B customer (a buyer) is a customer account in your platform that SparkLayer recognises as trade. Retail customers who aren't tagged keep shopping as normal.

- **Shopify:** a customer tagged `b2b`. SparkLayer adds the tag for you when you [invite a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md).
- **Wix:** a contact with the `b2b` label.
- **Other platforms:** see [Assign customers to a customer group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group).

### Customer groups

A [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md) is a set of ordering rules shared by a group of B2B customers:

- Which price lists they see
- Which payment methods they can use, such as card upfront or payment on account
- Order limits, such as a minimum order value
- Other rules, such as shipping and checkout options

Every account starts with a **Base customer group**. B2B customers are in it unless you put them in another group. To move a customer to another group, give them a second tag that matches it, such as `b2b-vip`. Customer groups are under **Customers** in the app.

### Companies

A [company](https://docs.sparklayer.io/help/customers/companies.md) is a business you sell to. On Shopify, these are your Shopify B2B companies. Larger companies can be split into [locations](https://docs.sparklayer.io/help/customers/company-locations.md), such as stores or regions.

### Company users

A B2B customer can invite colleagues to share their account as [company users](https://docs.sparklayer.io/help/customers/company-users.md). The whole team then sees the same orders, addresses and shopping lists. The main user can approve orders placed by limited users.

### Sales agents

[Sales agents](https://docs.sparklayer.io/help/sales-ordering.md) (sales reps) are members of your team who sign in to your store and order on behalf of the customers they look after. Each agent's role controls what they can do.

## The storefront

### Frontend interfaces

The [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) (or widgets) are the parts of SparkLayer your customers use:

- B2B product pricing
- A quick-order product matrix
- The My Cart checkout
- The My Account area, for reordering, invoices and addresses

They sit inside your existing theme and only appear for signed-in B2B customers. To choose how they look, see [Customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md).

### Checkout and payment

B2B customers check out in the My Cart interface. Depending on their [payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md), they either:

- Pay upfront by card in your platform's checkout
- Place the order on account, by invoice or as a quote request

Either way, the order arrives in your platform's admin.

## Going live

### Testing

To see SparkLayer as a buyer before your customers do, use [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order). It signs you in to your own store as a test B2B customer, and the test order doesn't count towards your plan.

To try changes on a second, test store, use [Test mode](https://docs.sparklayer.io/help/dashboard/test-mode.md).

### Plans

What you can use depends on your plan, and a few features also depend on your platform. Every paid plan has a 14-day free trial. See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md), [Your plan and usage](https://docs.sparklayer.io/help/dashboard/plan-and-features.md) and [Compare platforms](https://docs.sparklayer.io/help/platforms/compare.md).

## Under the hood

For the more technical: how SparkLayer's 3 parts connect your store, your website and any back-office systems, such as an ERP. You don't need this to get started.

How SparkLayer connects:

- **Backend:** B2B-specific data (price lists, product pack sizes, customer rules) comes from an ERP / CRM, a manual upload or an automatic sync, and is sent to the **SparkLayer Backend**, which stores it.
- **eCommerce platform** (e.g. Shopify): its core functions (order, catalogue and customer management, analytics, marketing and promotions, CMS) sync both ways with the **SparkLayer Connector**.
- **Website storefront:** core templates (homepage, collections, products, static pages, blog) work as normal. The **SparkLayer Frontend** overlays B2B widgets: product pricing, buy button, quick order form, checkout and ordering, and the My Account area.

## See it in action

Try SparkLayer for yourself as a B2B buyer on [our demo stores, or your own store](https://docs.sparklayer.io/help/get-started/demo.md).

SparkLayer works with Shopify, BigCommerce, Wix, WooCommerce and Magento. See [Platforms](https://docs.sparklayer.io/help/platforms.md) for what's supported on each, and [Architecture](https://docs.sparklayer.io/developers/architecture.md) for the technical detail.

## Next steps

You're ready to set up SparkLayer. The first step is installing it on your platform.

Not sure where to start? Answer 4 quick questions and get [your own setup guide](https://docs.sparklayer.io/help/get-started/setup-guide.md): the guides that apply to your store, in the order you need them.

- [Get started](https://docs.sparklayer.io/help/get-started.md): Set up SparkLayer with the 5 Setup steps
- [Find your platform](https://docs.sparklayer.io/help/platforms.md): Install guides for Shopify, BigCommerce, Wix, WooCommerce and Magento
- [Glossary](https://docs.sparklayer.io/help/glossary.md): Every SparkLayer term, defined
- [Contact support](https://docs.sparklayer.io/help/support.md): Book an onboarding call or ask our team


---

# Try our demo

URL: https://docs.sparklayer.io/help/get-started/demo

See SparkLayer in action: try the B2B ordering experience on your own website, or sign in to our Shopify demo store and place test B2B orders.

> **Quick summary**
>
> - Before you install, see SparkLayer's B2B ordering on your own website, with nothing installed. Or sign in to our Shopify demo store and place test orders.
> - The demo store is a combined retail and B2B store: anyone can browse, and B2B customers sign in to see their own pricing.
> - Already installed SparkLayer on Shopify? [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order) places a test order on your own store as a B2B buyer, and its **Launch live demo** button opens our live demo.
> - Want a guided tour? [Arrange a live demo](https://www.sparklayer.io/?demo#contact) with our team.

There are 2 ways to see SparkLayer before you install it. Once it's installed, use [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order) instead. It signs you in to your own store as a test B2B customer, with your real prices.

- [On your own store](#try-it-on-your-store): See B2B ordering on your website, with your products and branding
- [Demo store](#demo-stores): Sign in to our Shopify demo store and place test B2B orders

## Try it on your store

The fastest way to see SparkLayer is on your own store. Our interactive demo loads your website and overlays SparkLayer's B2B ordering on top. You can then place a wholesale order with your real products and branding. Nothing is installed, and nothing changes on your site.

To see SparkLayer on your own store, open https://www.sparklayer.io/?demo=www.yourstore.com with your store's domain in place of www.yourstore.com.

In the app, the **Launch live demo** button on **Orders > Place a test order** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Try it out** in the Shopify app opens a live demo in the same way. 

## Demo store

Our demo store runs SparkLayer on Shopify. Sign in to try B2B pricing, the checkout and [sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md), as your customers would.

### Hybrid DTC and B2B

![Hybrid DTC and B2B – Try our demo](https://docs.sparklayer.io/images/help/get-started/demo/demo-8f33df.webp)

A combined DTC (direct to consumer) and B2B store. Anyone can browse and buy, and B2B customers sign in to see their own pricing. It also shows multiple currencies. [Watch the walk-through video](https://26157419.fs1.hubspotusercontent-eu1.net/hubfs/26157419/SparkLayer%20Recorded%20Demo%20Video.mp4).

[Open the hybrid demo store](https://demo.sparklayer.io/pages/b2b-login-register)

### What to try

- [Product purchasing](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md): How customers add items to a B2B order
- [Checkout](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md): How the checkout works, such as choosing a payment method
- [My Account area](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md): How the self-service My Account area works

## Get a live demo

> **See it with our team**
>
> Our team walks you through SparkLayer and shows you how it all works. [Arrange a live demo](https://www.sparklayer.io/?demo#contact).

## Next steps

- [Get started](https://docs.sparklayer.io/help/get-started.md): Ready to set up? Follow the 5 Setup steps
- [How SparkLayer works](https://docs.sparklayer.io/help/get-started/how-sparklayer-works.md): How it fits with your store, plus price lists, customer groups and the other essentials


---

# Launch checklist

URL: https://docs.sparklayer.io/help/get-started/launching

Work through the SparkLayer launch checklist: test as a B2B customer, check SKUs, pricing and payments, invite your first customers, then go live for everyone.

> **Quick summary**
>
> - Launching has 3 phases: **test** SparkLayer yourself, **invite** a first group of customers, then **launch** to all your B2B customers. Each phase is a short list of tasks to tick off.
> - Start once you have a price list assigned to a customer group, and SparkLayer on your theme. The steps on **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app cover this, or your platform's install guide on other platforms. See [Get started](https://docs.sparklayer.io/help/get-started.md).
> - On Shopify, **Try it out** is the quickest test: it signs you in as a test B2B customer and places a test order that doesn't count towards your plan.
> - Many checks happen in your store's admin, such as customer tags, SKUs and sales channels. Steps are given for Shopify and Wix. For other platforms, see your [platform guide](https://docs.sparklayer.io/help/platforms.md).
> - Want the whole journey, from setup to launch, for your store? Build [your setup guide](https://docs.sparklayer.io/help/get-started/setup-guide.md).
> - Our team can help you go live. On a paid plan, [book an onboarding call](https://book.sparklayer.io/). See [Contact support](https://docs.sparklayer.io/help/support.md).

1. **Test:** check everything works the way your customers will see it.
2. **Invite:** invite a first group of customers and gather their feedback.
3. **Launch:** go live and bring the rest of your B2B customers on board.

## Phase 1: Test

Test SparkLayer the way your customers will use it, so you know everything works before anyone else sees it.

> **Before you start**
>
> - **A price list** 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 (a test one is fine), assigned to a customer group at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app (the **Base customer group** is fine).
> - **SparkLayer on your theme**, added by you or our team. On Shopify, check [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md). On other platforms, see your [platform guide](https://docs.sparklayer.io/help/platforms.md).

### Create a test B2B customer and sign in

Set up an example B2B customer and browse your store as them.

**Shopify:**

The quickest way is **Try it out**. Its **Test as a B2B customer** step uses or creates a customer with the `b2b` tag. **Open store as test customer** then opens your store signed in as them.

You can also set up a test customer by hand. SparkLayer only loads for customers tagged `b2b` in Shopify.

1. In your Shopify admin, go to **Settings > Customer accounts** ([open in the Shopify admin](https://admin.shopify.com/settings/customer_accounts)) and choose **Customer accounts** or **Legacy accounts**, so customers can sign in. Both work with SparkLayer.
2. Go to **Customers** ([open in the Shopify admin](https://admin.shopify.com/customers)) and open an existing customer, or click **Add customer**.
3. Fill in all the fields, including the address. SparkLayer can't find a customer record that has no address.
4. In the customer's **Tags** box, type `b2b` and choose the existing tag or create it. To put the customer in a group other than **Base**, add that group's tag as well, for example `b2b-account`.
5. Give the customer access:
   - With **Customer accounts**, there's nothing to send. The customer goes to your sign-in page (for example `www.yourstore.com/account`), enters their email and receives a 6-digit code.
   - With **Legacy accounts** and a new customer record, open the customer and click **More actions** > **Send account invite**. The customer receives an email with an **Activate your account** button, and sets a password. You can edit the [account activation email](https://admin.shopify.com/email_templates/customer_account_activate/preview). See Shopify's guide to [inviting customers to create accounts](https://help.shopify.com/en/manual/customers/customer-accounts#invite-customers-to-create-accounts).
6. Go to your store's sign-in page (for example `www.yourstore.com/account`) and sign in as the customer. With Customer accounts, enter the 6-digit code sent to the customer's email.

SparkLayer loads, and you can browse your store as a B2B customer. If you can't reach the sign-in page, check customer accounts are turned on (step 1).

**Wix:**

SparkLayer only syncs Wix contacts that have the `b2b` label and are site members.

1. In your Wix dashboard, go to **Customers & Leads > Contacts**. Create a new contact or edit an existing one.
2. Fill in a valid address, with every address field completed. Note the email address, as you'll need it to sign in.
3. In the contact's **Labels** section, click **Add Label** and add `b2b`.
4. Check the contact is a site member: under **Member info**, the **Member status** shows **Site Member**. Only site members can sign in to your store.
5. If you've created other customer groups at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app, add their labels exactly as they appear in SparkLayer, for example `b2b` and `b2b-additional-group`. Don't edit a label in Wix after you've added it.
6. Sign in to your store as the customer.

Every account has a **Base customer group** you can use for your B2B customers. Once at least one customer has a group's label, you can manage that group's rules at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app. For different rules, click **Create customer group**, then add the new group's label to customers in Wix (for example `b2b` and `b2b-account`).

**Other platforms:**

How you create a B2B customer depends on your platform. See your platform's guide in [Platforms](https://docs.sparklayer.io/help/platforms.md).

To check the customer has synced to SparkLayer, go to **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app and search for their name or email. If they're listed with their customer group, they've synced.

If they're missing, check the sync banner at the top of the page. Click **Show errors** to see which customers didn't sync and why, such as a missing address. Fix them in your store's admin, and they sync on the next partial sync. See [Monitoring data sync](https://docs.sparklayer.io/help/integrations/data-sync.md).

### Check your products have unique SKUs

SparkLayer matches prices to products by SKU, so every product needs a unique one.

SparkLayer matches prices and its storefront widgets to products by SKU. Without SKUs, it can't show B2B pricing or its widgets. Every product you want B2B customers to see prices for must have a SKU, and each SKU must be unique (for example `MUG-CAT` and `MUG-DOG`).

**Shopify:**

1. Go to **Products** ([open in the Shopify admin](https://admin.shopify.com/products)) and open a product.
2. Check the **SKU (Stock Keeping Unit)** field in the **Inventory** section, and on each variant.
3. To add SKUs, edit products one by one, or add them in bulk with Shopify's **Import** feature or an app such as [Matrixify](https://apps.shopify.com/excel-export-import).

If two products share a SKU, change one so every SKU is unique.

**Wix:**

1. Go to **Catalog > Store Products > Products** and edit a product.
2. For a product without variants, add the SKU in the **SKU** field of the **Inventory and shipping** section.
3. For a product with variants (such as colour or size), turn on **Manage pricing and inventory for each product variant**, then add a SKU for each variant in the **Product variants** section.

**Other platforms:**

Check each product's SKU in your platform's product admin.

### Check your products are in the SparkLayer sales channel (Shopify only)

Products must be active and in the SparkLayer Wholesale sales channel.

**Shopify only:**

SparkLayer only shows B2B prices for products in both the **Online Store** and **SparkLayer Wholesale** sales channels. Products must also have the status **Active**. SparkLayer doesn't import draft products.

1. In your Shopify admin, go to **Products** ([open in the Shopify admin](https://admin.shopify.com/products)) and open a product.
2. Check its **Status** is **Active**.
3. In the product's sales channel settings, check **Online Store** and **SparkLayer Wholesale** are both selected. 

To make a product unavailable to B2B customers, leave it out of the **SparkLayer Wholesale** channel.

To check what SparkLayer has for a product, search for it at **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app.

### Check your B2B prices

Sign in as your test customer and check they see their B2B prices.

Sign in as your test customer and check the prices on your product pages.

No B2B prices? SparkLayer doesn't show any until you've added a price list and assigned it to the customer's group. These are steps 1 and 2 of the Setup checklist: see [Work through the steps](https://docs.sparklayer.io/help/get-started.md#work-through-the-steps).

If the prices are there but not the ones you expect, see [Prices are different from what you expect](https://docs.sparklayer.io/help/troubleshooting.md#prices-are-different-from-what-you-expect).

### Set up B2B shipping (optional)

Only if you want shipping rules just for your B2B customers.

By default, SparkLayer uses the shipping rules in your eCommerce platform, such as Shopify. To show B2B-only shipping rules to your B2B customers, set them up at **Settings > Shipping** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping** in the Shopify app. See [Shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md) for both options.

Skip this step if your platform's shipping rules suit your B2B customers.

### Place a test order

Check out with each payment method, then see how each order arrives in your admin.

As your test customer, go to any product page and add items. They appear in the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md). Check out once with each payment method you offer, then check how each order arrives in your admin.

**Shopify only:**

The **Place a test order** step of **Try it out** opens your store as the test customer. Its test orders don't count towards your plan.

**Shopify:**

**Payment methods**

At the payment step, customers choose from the payment methods their customer group allows (set under **Payment methods** on the [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md#choose-payment-methods)):

| At checkout | In the customer group | For the customer | How the order arrives in Shopify |
| --- | --- | --- | --- |
| **Pay on Account** | **Payment on account** | Checks out without entering payment details. You can set credit limits and net terms such as Net 30: see [Credit limits and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md). | As a **draft order**, which stays a draft until it's paid. |
| **Pay by Invoice** | **Pay by invoice** | Checks out without entering payment details. You take payment offline, for example by bank transfer. | As a **draft order**, which stays a draft until it's paid. |
| **Pay Online by Card** | **Card at checkout** | Goes to your Shopify checkout and pays straight away, by card or another payment provider. Sometimes called upfront or pro-forma payment. | As a **completed order**, marked **Paid** and ready to fulfil. The customer gets Shopify's order notification. |

Quote requests from the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md) don't create a Shopify order straight away. It waits for your reply, and becomes an order once it's accepted. See [Work on a quote](https://docs.sparklayer.io/help/ordering/work-on-a-quote.md).

How B2B payment methods work with SparkLayer and Shopify, starting from the B2B checkout (SparkLayer):

- **Pay online by card (upfront):**
  - If it's a **sales agent order**, or a **company user order**, an email is sent to the customer to complete payment. The customer clicks the link, pays in the **Shopify checkout** and the order is completed in Shopify.
  - Otherwise the customer pays in the **Shopify checkout** and the order is completed in Shopify.
- **Payment on account or by invoice:** the order is completed in SparkLayer ("Order completed (SparkLayer)").
  - If **auto-complete draft orders** is on, a completed order is created in Shopify.
  - If it's off, a draft order is created in Shopify, which becomes a completed order once it's manually marked as complete.

To create completed orders instead of draft orders, turn on **Auto-complete draft orders** at **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app.

If a customer chooses Pay Online by Card but doesn't finish paying, the order still appears in your Shopify draft orders for review.

**Payment methods at the Shopify checkout**

Customers who choose Pay Online by Card go to the Shopify checkout. There, they see all the payment methods you've set up in Shopify, such as card or PayPal. To limit which ones B2B customers see, try an app such as [Payfy Conditional Payments](https://apps.shopify.com/payfy-conditional-payments).

**Find your B2B orders in Shopify**

Every order placed through SparkLayer is tagged `b2b`. To see only B2B orders, open [B2B-tagged orders in Shopify](https://admin.shopify.com/store/orders?tag=b2b), or add `orders?tag=b2b` to your Shopify admin URL.

**Extra details SparkLayer adds to orders (for automations and developers)**

| Attribute | What it contains |
| --- | --- |
| `tag` | `b2b` is added to every order placed through SparkLayer. Use it to filter and segment orders, or in automations. |
| `note` | `sparkCartId`, added as an order note. Mainly for internal use and debugging. |
| `note` | `sparkPaymentType`, added as an order note: the payment option used (`upfrontPayment`, `paymentOnAccount`, `paymentByInvoice` or `quote`). |

**Wix:**

**Payment methods**

Orders appear in **Sales > Orders** in your Wix dashboard:

| At checkout | In the customer group | For the customer | How the order arrives in Wix |
| --- | --- | --- | --- |
| **Pay on Account** | **Payment on account** | Checks out without entering payment details. | Payment status **UNPAID**. Mark it as paid once you've received payment. |
| **Pay by Invoice** | **Pay by invoice** | Checks out without entering payment details. | Payment status **UNPAID**. Mark it as paid once you've received payment. |
| **Pay Online by Card** | **Card at checkout** | Goes to your Wix checkout and pays straight away, by card or another payment provider. | Payment status **PAID**, ready to fulfil. |

Customers who choose Pay Online by Card see all the payment methods you've set up in Wix, such as card or PayPal.

**Other platforms:**

See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md) for how each method works, and your [platform guide](https://docs.sparklayer.io/help/platforms.md) for how orders arrive in your admin.

### Check the design

Make sure SparkLayer's widgets match your store's fonts, colours and buttons.

Sign in as your test customer and check SparkLayer's widgets match your store's look, such as its fonts, colours and buttons. If our team installed SparkLayer for you, this styling is already done. If not, we recommend adding some basic styling with CSS. That's usually a job for your developer or our team. See [Customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md).

### Set up B2B sign-in and registration

Decide how B2B customers sign in, and how new ones apply for a trade account.

If you invite your B2B customers yourself, you might not need a registration form. See [Inviting](#inviting).

**Shopify only:**

On Shopify, there are two recommended ways to let customers sign in and apply for a trade account: 

1. **SparkLayer Forms (recommended).** Build B2B registration forms at **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)) with the no-code form builder. You don't need any third-party apps. Start from the ready-made **Customer Registration Form** template, which includes approval workflows, automatic customer tagging and email notifications. Forms are in the SparkLayer Dashboard at app.sparklayer.io, not in the Shopify app. See [Forms](https://docs.sparklayer.io/help/forms.md).
2. **Our B2B login and register page.** A ready-made page template that includes a registration form. You can see it on our [demo store](https://docs.sparklayer.io/help/get-started/demo.md). See [Shopify B2B registration and login](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md).

On other platforms, see your [platform guide](https://docs.sparklayer.io/help/platforms.md).

### Turn on extra B2B features (optional)

Live stock, pack sizes, B2B-only products, RRPs and more.

You can add features such as live stock levels, pack sizes, B2B-only products and retail prices (RRP). Try them on [our demo stores](https://docs.sparklayer.io/help/get-started/demo.md), or see [Storefront features](https://docs.sparklayer.io/help/storefront.md).

| Area | Features |
| --- | --- |
| Customer experience | [B2B login page](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md), [B2B registration page](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md), [hide B2B products from retail (DTC) customers, show B2B-only content and create a B2B-only navigation menu](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-only-content.md), [B2B email notifications](https://docs.sparklayer.io/help/platforms/shopify/customisations/email-notifications.md) (Shopify) |
| Checkout | [B2B-only shipping](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md), [B2B payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md), [custom checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md) |
| Products | [Pack sizes and minimum or maximum quantities](https://docs.sparklayer.io/help/storefront/quantity-rules.md), [live stock levels, pre-orders and back-orders, and reserved stock for DTC customers](https://docs.sparklayer.io/help/storefront/stock-display.md) |
| Automations | [Shopify Flow ready-made automations](https://docs.sparklayer.io/help/platforms/shopify/customisations/flow.md) (Shopify) |

**Ready for the next phase:** A test order has arrived in your admin the way you expect, and your store looks right to a B2B customer. If something doesn't work as expected, see 

[Troubleshooting](https://docs.sparklayer.io/help/troubleshooting.md)

.

## Phase 2: Invite

Once you're happy everything works, invite a first group of customers. Test the whole journey end to end before you do. Starting with a small group lets you gather feedback before you invite everyone.

### Invite your first customers

Start with a small group, so you can gather feedback before you invite everyone.

**Shopify:**

The quickest way is 

**Invite a buyer**

, on step 3 of 

**Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app

 or at 

**Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app

 (

**Invite buyer**

). Enter the buyer's email, choose their 

**Customer group**

 and click 

**Send invite**

. SparkLayer adds them to Shopify with the group's tag, and they see trade prices as soon as they sign in. See 

[Invite a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md)

.

To invite customers you've already set up in Shopify (see [Add B2B customers on Shopify](https://docs.sparklayer.io/help/platforms/shopify/invite-customers.md) for adding them one at a time, in bulk or from scratch):

1. Check customer accounts are turned on in **Settings > Customer accounts** ([open in the Shopify admin](https://admin.shopify.com/settings/customer_accounts)) (**Customer accounts** or **Legacy accounts**).
2. For each customer, follow steps 2 to 5 of [Create a test B2B customer and sign in](#create-a-test-b2b-customer-and-sign-in): complete their record including the address, tag them `b2b`, and send an account invite if you use Legacy accounts.
3. Tell the customer to go to your sign-in page (for example `www.yourstore.com/account`). With Customer accounts, they enter their email and then a 6-digit code. With Legacy accounts, they sign in with their email address and password.

Once signed in, they see SparkLayer load and can browse your store as a B2B customer. If they can't reach the sign-in page, check customer accounts are turned on.

**Wix:**

1. Set up each customer as in [Create a test B2B customer and sign in](#create-a-test-b2b-customer-and-sign-in). Any contact with the `b2b` label syncs to SparkLayer automatically. To sign in, they must also be a site member.
2. Let your customers know they can sign in and start ordering:
   - To message one customer, go to **Customers & Leads > Contacts**, open the contact and use the **Inbox** tab to send a direct message.
   - To email several customers, go to **Customers & Leads > Contacts**, search or filter, select the customers and click **Send Email Campaign**.

You can start from our [example welcome email](#send-a-welcome-email).

**Other platforms:**

See your [platform guide](https://docs.sparklayer.io/help/platforms.md) for how to set up and invite customers.

### Invite customers in bulk (optional)

Create and invite lots of customers at once with an app.

**Shopify only:**

On Shopify, apps can create and invite many customers at once:

- [Matrixify](https://apps.shopify.com/excel-export-import?st_source=autocomplete) has tools to create customer records and invite them quickly.
- [BAIS Bulk Account Invite](https://apps.shopify.com/bulk-account-invite-sender?) invites customers in bulk without sending them emails.

On other platforms, see your [platform guide](https://docs.sparklayer.io/help/platforms.md).

### Automate approval of new customers (optional)

Let customers apply for access, and review each application.

**Shopify only:**

On Shopify, customers can apply for access on your store, and you review each application before they can place B2B orders. See the options in [Shopify B2B registration and login](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md).

On other platforms, see your [platform guide](https://docs.sparklayer.io/help/platforms.md).

**Ready for the next phase:** Your first customers are signing in and ordering without problems.

## Phase 3: Launch

When your first customers are ordering without problems, launch your B2B store fully and invite the rest of your customers.

### Turn off preview mode (Shopify only)

If your store shows a preview mode banner, finish the last launch step in the app.

**Shopify only:**

A **preview mode** banner on your store means the final launch step in the SparkLayer Wholesale app isn't done yet.

1. In your Shopify admin, under **Sales channels**, click **SparkLayer Wholesale** to open the app's **Home**.
2. Click **Start taking B2B orders**.

If you don't see **Start taking B2B orders**, the app thinks a setup step isn't complete, such as **Add SparkLayer to your theme**. Check every step at **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app is ticked off. See [Work through Setup](https://docs.sparklayer.io/help/platforms/shopify/install.md#work-through-setup).

**More detail**

If every step looks done and the button still isn't there, [contact our support team](https://docs.sparklayer.io/help/support.md). We may need collaborator access to your Shopify store, with the **Apps and channels** permission, to check the app's setup.

### Add an onboarding landing page

A ready-made page that explains the benefits of your B2B store.

Explaining the benefits encourages customers to use your new B2B store. Our ready-made onboarding landing page does this for you. Headed "Welcome to our B2B store", it introduces the B2B cart and My Account area. It also lists what customers can do, such as view their order history, track orders, download invoices and update their addresses.

**Shopify:**

1. In your Shopify admin, go to **Online Store > Pages** ([open in the Shopify admin](https://admin.shopify.com/pages)) and click **Add page**.
2. In the **Content** editor, click **Show HTML** and paste in the [page code from this gist](https://gist.github.com/cm-sl/47d750425f90d527e1210efe3735dc7f). 
3. Change the **Title** and content as you like.
4. Under **Search engine listing**, set the **URL handle** to `b2b-onboarding` (our recommendation).
5. Under **Visibility**, choose **Visible**, then save. Click **View** to see the page.
6. Link to the page from your store's navigation, such as the header or footer. If you use our [B2B registration and login page](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md), you can link to it from there too.

**Other platforms:**

See your platform's own help for how to create a custom landing page.

### Create a landing page for signed-in B2B customers (optional)

A hub B2B customers see as soon as they sign in.

You can also create a landing page that B2B customers see as soon as they sign in. Use it to highlight products, share important information or act as the hub of your B2B store. See [Shopify B2B landing page](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-landing-page.md).

### Send a welcome email

Invite the rest of your customers with our example email.

Use our example email to invite your customers, as a newsletter or a personal email from your B2B sales team. Replace the text in square brackets with your own details.

The example is written for Shopify's Legacy customer accounts, where customers activate their account and set a password. If you use new customer accounts, or invite buyers with **Invite a buyer**, rewrite the **Account Activation** part. Tell customers to go to your store's sign-in page and enter their email, then the one-time code they're sent.

**Example welcome email**

Dear \[Valued Partner],

We're excited to announce our new online B2B store and we're excited to have you join!

To ensure a smooth start, we've put together a guide to help you activate your account and start placing orders.

**Account Activation: The First Step to Joining**

- **Look Out for Our Email:** Keep an eye on your inbox for an email from \[My Store] with the subject "Activate Your \[My Store] Partner Account."
- **Activate with a Click:** Within that email, you'll find the 'Activate My Account' button. Click it to move forward with your activation.
- **Secure Your Login:** Follow the link to create your own secure password. After this, your account is all set and ready to go.

**B2B Portal: Streamlining Your Business**

- **Fast Track with Quick Order:** Speed is essential in business. That's why our 'Quick Order' feature offers a simple layout to place your orders quickly and efficiently - perfect for when you know exactly what you need.
- **Explore Products in Detail:** Curious about a product? Visit the 'Products' page for an in-depth look at the benefits, and quickly add to your order

**Effortless Account Management**

- **Your Orders, Simplified**: By clicking on the 'Account' or 'Cart' icons, you can view your Order Summary, adjust account settings, and monitor your orders in real-time.
- **Get a Shipping Quote:** Ready to finalise your order? Get live shipping costs right before you place your order
- **Approval Before Payment:** If you need administrative approval, select 'Pay on Account' to submit your order and we'll take care of the rest.

**Account Extras:**

Within 'My Account,' you'll also discover tools to:

- Review your order history.
- Save personalised shopping lists for quick reordering.
- Update your shipping addresses whenever necessary.

**We're Here for You**

Should you have any questions or need assistance, our dedicated team is ready to help at \[Your Support Email].

Thank you for choosing \[My Store] as your partner, we're excited to have you on board!

Warm regards,

\[Your Name] \[Your Position] \[My Store] \[Contact Information]

### Promote your B2B store on your website

Help B2B customers find your B2B store from your website.

A few changes to your website help B2B customers find your B2B store:

1. **Navigation:** add a clear link in your header or footer. On Shopify, edit your menus in **Online Store > Navigation** ([open in the Shopify admin](https://admin.shopify.com/menus)).
2. **Landing page:** set up a page to attract new and existing customers, with graphics, the benefits of your B2B store, testimonials and featured products.
3. **Emails:** update your email marketing to promote your new B2B store.

**You're live.** All your B2B customers are invited and ordering. Here's where to go next.

## After you launch

- [Orders](https://docs.sparklayer.io/help/dashboard/orders.md): See the B2B orders coming in through SparkLayer, and your sales over time
- [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md): Add groups for different prices, payment methods and order limits
- [Storefront features](https://docs.sparklayer.io/help/storefront.md): Pack sizes, stock display and the other options for your B2B store
- [Contact support](https://docs.sparklayer.io/help/support.md): Contact our team if anything isn't working as expected

## Additional resources

We also publish guides to help you grow your B2B and wholesale business.

- [Micropaper: Unlocking customer adoption](https://www.sparklayer.io/adoption/): Plan and deliver a strategy that gets your B2B customers ordering online.
- [Micropaper: Reimagining B2B operations](https://www.sparklayer.io/reimagine/): The wholesale tactics brands are using to stay ahead.
- [Micropaper: Simplifying B2B success](https://www.sparklayer.io/simplify/): Ways to make B2B ordering simpler for your team and your trade customers.
- [Video series: Acquire, onboard, retain and adopt](https://www.sparklayer.io/b2b-journey/): A free video series for brands, wholesalers and distributors on the B2B customer journey, from winning customers to keeping them.
- [Love B2B eCommerce, by SparkLayer](https://www.sparklayer.io/love-b2b-ecommerce/): A free toolkit for growing your B2B eCommerce business, with expert videos, strategy guides, case studies and 1:1 consultations.


---

# Guides

URL: https://docs.sparklayer.io/help/guides

Step-by-step guides to common B2B goals in SparkLayer, from setting trade prices and payment terms to shipping, tax, sign-up and moving customers across.

> **Quick summary**
>
> - Each guide takes one goal, such as giving a key account their own prices, from start to finish. It links to the detailed page for each step.
> - Every guide says what you'll end up with, how long it takes and which plan or platform it needs. Steps that differ by platform are labelled.
> - New to SparkLayer? Start with [Set up wholesale prices](https://docs.sparklayer.io/help/guides/set-up-wholesale-prices.md), or work through [Get started](https://docs.sparklayer.io/help/get-started.md).

## Pricing

- [Set up wholesale prices for your trade customers](https://docs.sparklayer.io/help/guides/set-up-wholesale-prices.md): You'll be able to give your buyers trade prices they see when they sign in.
- [Give a key account their own prices](https://docs.sparklayer.io/help/guides/key-account-prices.md): You'll be able to give one company or customer different prices from their group.
- [Move brand discounts from another wholesale app](https://docs.sparklayer.io/help/guides/migrate-brand-discounts.md): You'll be able to recreate per-brand trade discounts with price lists and customer groups.
- [Run volume pricing and promotions](https://docs.sparklayer.io/help/guides/volume-discounts.md): You'll be able to reward bigger orders with price breaks, pack sizes and discounts.
- [Show RRPs to your trade customers](https://docs.sparklayer.io/help/guides/show-rrp.md): Fill in every product's RRP from your Shopify prices or a spreadsheet
- [Get B2B tax and VAT right](https://docs.sparklayer.io/help/guides/tax-and-vat.md): You'll be able to show net prices and charge VAT or sales tax once.

## Payments and orders

- [How payments work](https://docs.sparklayer.io/help/guides/how-payments-work.md): You'll be able to follow each payment method from checkout to payment, and choose which to offer.
- [Let trusted customers pay later on Net 30](https://docs.sparklayer.io/help/guides/net-terms.md): You'll be able to offer pay on account, with credit limits and payment terms.
- [Process your B2B orders in Shopify](https://docs.sparklayer.io/help/guides/process-orders-in-shopify.md): You'll be able to complete draft orders, take payment and give buyers invoices.
- [Show imported or manual orders in My Account](https://docs.sparklayer.io/help/guides/show-imported-orders.md): You'll be able to show draft and historic orders in your customers' order history.
- [Charge the right shipping on B2B orders](https://docs.sparklayer.io/help/guides/b2b-shipping.md): You'll be able to show each customer group the right shipping methods and costs.

## Customers and your store

- [Keep wholesale hidden from retail shoppers](https://docs.sparklayer.io/help/guides/hide-wholesale-from-retail.md): You'll be able to hide B2B products and prices from everyone but your trade customers.
- [Hide products from customers](https://docs.sparklayer.io/help/guides/hide-products.md): You'll be able to hide products, such as custom products or fees, from every B2B customer or some customer groups.
- [Sell a B2B-only version of a product](https://docs.sparklayer.io/help/guides/sell-b2b-only-versions.md): You'll be able to sell a trade pack, such as a case of 12, that only B2B customers see.
- [Let new trade customers apply, and approve them](https://docs.sparklayer.io/help/guides/approve-trade-applications.md): You'll be able to take trade account applications and approve each buyer into a group.
- [Move your existing wholesale customers onto SparkLayer](https://docs.sparklayer.io/help/guides/move-existing-customers.md): You'll be able to bring your trade customers, their terms and their order history across.
- [Fix customers or products that won't sync](https://docs.sparklayer.io/help/guides/fix-sync-problems.md): You'll be able to find and fix the records that stop buyers seeing their prices.


---

# Set up wholesale prices for your trade customers

URL: https://docs.sparklayer.io/help/guides/set-up-wholesale-prices

Create a B2B price list, add your trade prices, assign it to a customer group and add your buyers, then sign in as a buyer to check the prices they see.

> **Quick summary**
>
> - You'll end up with a price list of trade prices, a customer group that uses it, and buyers who see those prices when they sign in.
> - Most stores finish the core steps in under 15 minutes. Allow longer if you're preparing a spreadsheet of exact prices.
> - Works on every plan and platform. The free Basic plan includes 3 price lists; Starter and above have unlimited price lists.

A buyer's prices come from a price list, and a customer group decides who sees it. This guide sets up both, then adds your buyers and checks what they see. For the ideas behind it, see [Key concepts](https://docs.sparklayer.io/help/get-started/how-sparklayer-works.md#key-concepts).

## Before you start

- **SparkLayer installed on your store.** On Shopify, see [Install SparkLayer on Shopify](https://docs.sparklayer.io/help/platforms/shopify/install.md). On other platforms, see [Platforms](https://docs.sparklayer.io/help/platforms.md).
- **A unique SKU on every product** you sell to B2B customers, and the product set to active. Prices are matched to products by SKU.
- **Your trade prices, or the rule for them**, for example 20% off your retail prices. A spreadsheet of prices by SKU is fine.
- **An email address you can sign in to**, to test as a buyer.

## Set it up yourself

### Step 1. Create a price list

This is step 1 of the Setup checklist: see [Set up a price list](https://docs.sparklayer.io/help/get-started.md#set-up-your-b2b-pricing). Give it a name your team will recognise, such as "Trade GBP", and pick its **Currency** with care: you can't change the **Handle** or **Currency** later. See [Create a price list](https://docs.sparklayer.io/help/pricing/managing-pricing.md#create-a-price-list). [Take the 1-minute tour](https://docs.sparklayer.io/help/pricing/managing-pricing?tour).

### Step 2. Add your trade prices

Choose how the list gets its prices:

| If your trade prices are… | Do this |
| --- | --- |
| A set percentage off retail | Tick **Enable automatic pricing**, choose a **Pricing source** and enter the percentage. See [Set up automatic pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md#set-up-automatic-pricing). |
| Exact prices in a spreadsheet | Save it as a CSV file with **SKU** and **Price** columns, then click **Upload** next to the list. See [Upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md). |

Upload prices without tax. SparkLayer shows prices net and adds tax at checkout: see [step 5](#check-your-prices-allow-for-tax).

### Step 3. Assign the price list to a customer group

This is step 2 of the Setup checklist: see [Assign a price list to a customer group](https://docs.sparklayer.io/help/get-started.md#set-up-your-customer-groups). To give every B2B customer these prices, use the **Base customer group**. To give them to some customers only, create a customer group for them. See [Assign price lists](https://docs.sparklayer.io/help/customers/customer-groups.md#assign-price-lists). [Take the 1-minute tour](https://docs.sparklayer.io/help/customers/customer-groups?tour).

**More detail**

A group can have several price lists, and their order decides which price a customer sees for a SKU that's in more than one. See [Price list order](https://docs.sparklayer.io/help/pricing/managing-pricing.md#price-list-order).

### Step 4. Add your buyers to the group

Each customer belongs to one customer group. On Shopify, this is step 3 of the Setup checklist: see [Add your first buyer](https://docs.sparklayer.io/help/get-started.md#add-your-b2b-customers). Give each buyer the group's tag as well as `b2b` if it isn't the Base group, for example `b2b-trade`.

On other platforms, you mark B2B customers in your platform's admin, such as the `b2b` label on Wix: see [Other platforms](https://docs.sparklayer.io/help/get-started.md#other-platforms). For every platform, see [Assign customers to a customer group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group).

### Step 5. Check your prices allow for tax

Customers see exactly the price in their price list, before tax. Tax is added at the last step of checkout.

**Shopify only:**

In your Shopify admin, go to **Settings > Taxes and duties** ([open in the Shopify admin](https://admin.shopify.com/settings/taxes)). If **Include sales tax in product price and shipping rate** is on and you use an automatic price list, raise its percentage to take the tax out too. Otherwise customers pay tax twice. See [Tax-inclusive prices](https://docs.sparklayer.io/help/pricing/managing-pricing.md#tax-inclusive-prices).

**BigCommerce and Wix and WooCommerce and Magento only:**

SparkLayer uses your platform's tax rules. Check the limits for your platform in [Set up tax on other platforms](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md#set-up-tax-on-other-platforms).

For VAT and tax-exempt customers, see the guide [Get B2B tax and VAT right](https://docs.sparklayer.io/help/guides/tax-and-vat.md).

### Step 6. Test as a B2B customer

Sign in to your store as a buyer in the group and check the prices, payment methods and any minimum order.

**Shopify only:**

Go to **Orders > Place a test order** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Try it out** in the Shopify app. It creates a test customer with the `b2b` tag, gives them a price list and opens your store signed in as them. Test orders don't count towards your plan. See [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order).

**BigCommerce and Wix and WooCommerce and Magento only:**

Create a test customer in your platform, add them to the group as in step 4, then sign in to your store as them. See [Test as a B2B customer](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#test-as-a-b2b-customer).

## Check it worked

Signed in as your test buyer:

- **Product pages show the price list's price**, for example $7.99 for a SKU listed at 7.99.
- **The cart shows the same prices**, with tax added as its own line on **Review & Pay**.
- **The buyer shows in the right group** at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app, in the **Group** column.

To check one product's price in every list, search for its SKU at **Pricing > Price editor** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/editor)), or **SparkLayer Wholesale > Pricing > Price editor** in the Shopify app.

## If something's not right

- **The buyer sees retail prices, or products say "Unavailable".** Check their tag, their sync status and that the product is in a price list their group uses. See [Customers can't see B2B prices](https://docs.sparklayer.io/help/troubleshooting.md#customers-cant-see-b2b-prices-or-products-say-unavailable).
- **A price isn't the one you expected.** The SKU may be in an earlier price list on the group (see [Price list order](https://docs.sparklayer.io/help/pricing/managing-pricing.md#price-list-order)), or your store prices may include tax. See [Prices are different from what you expect](https://docs.sparklayer.io/help/troubleshooting.md#prices-are-different-from-what-you-expect).
- **Tax is charged twice.** Upload net prices, and make automatic lists allow for tax. See [Tax is charged twice](https://docs.sparklayer.io/help/troubleshooting.md#tax-is-charged-twice).
- **Some CSV rows were skipped.** Check each SKU matches your store exactly and prices have no currency symbol. See [Skipped rows](https://docs.sparklayer.io/help/pricing/csv-upload.md#skipped-rows).

## Next steps

- [Give a key account their own prices](https://docs.sparklayer.io/help/guides/key-account-prices.md): Set different prices for one company or customer
- [Get B2B tax and VAT right](https://docs.sparklayer.io/help/guides/tax-and-vat.md): Show net prices and charge VAT once
- [Let trusted customers pay later on Net 30](https://docs.sparklayer.io/help/guides/net-terms.md): Offer pay on account with credit limits and terms
- [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md): Test everything, then invite your customers


---

# Give a key account their own prices

URL: https://docs.sparklayer.io/help/guides/key-account-prices

Give one company or customer prices different from their customer group: their own price list, an extra percentage off, or a group of their own.

> **Quick summary**
>
> - You'll end up with one key account seeing their own prices when they sign in, while everyone else in their customer group keeps theirs.
> - Allow about 15 minutes once their prices are ready.
> - Every plan includes it. A company price list is set in SparkLayer, for Shopify stores that use companies. A customer's own price list or extra discount is set on their record in your store, and isn't available on Wix.

Most buyers get their prices from their [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md). For a key account, you set a price list at a more specific level, and the most specific one wins. See [What overrides what](https://docs.sparklayer.io/help/customers.md#who-sets-what).

## Before you start

- **Their prices, or the rule for them**, for example 30% off retail, or a spreadsheet of exact prices by SKU.
- **Your standard trade prices set up.** If not, follow [Set up wholesale prices](https://docs.sparklayer.io/help/guides/set-up-wholesale-prices.md) first.
- **The account in SparkLayer.** Find the company at **Companies** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/companies)), or **SparkLayer Wholesale > Companies** in the Shopify app, or the customer at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app.

## Give them their prices

### Step 1. Choose how to give them their prices

| For | Use | Where you set it |
| --- | --- | --- |
| **A whole business**, with everyone who orders for it | A price list on the [company](https://docs.sparklayer.io/help/customers/companies.md#prices-and-rules) | In SparkLayer (Shopify) |
| **One customer** | Their own price lists, with [customer pricing](https://docs.sparklayer.io/help/pricing/customer-pricing.md#give-a-customer-their-own-price-lists) | On their record in your store |
| **One customer, a little extra off** | An [extra percentage discount](https://docs.sparklayer.io/help/pricing/customer-pricing.md#give-a-customer-an-extra-percentage-discount) on top of their usual prices | On their record in your store |
| **Several key accounts on the same terms** | A [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md#create-a-customer-group) of their own | In SparkLayer, on every platform |

For an extra percentage off, skip to [step 4](#add-an-extra-percentage-off).

### Step 2. Create their 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, click **Create price list** and add their prices, automatically or by CSV. Note the list's **Handle**, shown under its name, such as `acme-pricing`. See [Create a price list](https://docs.sparklayer.io/help/pricing/managing-pricing.md#create-a-price-list). [Take the 1-minute tour](https://docs.sparklayer.io/help/pricing/managing-pricing?tour).

### Step 3. Give the price list to the account

**Shopify only:**

**For a company:**

 go to 

**Companies** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/companies)), or **SparkLayer Wholesale > Companies** in the Shopify app

, click the company's name and, under 

**Prices and rules**

, choose the 

**Price list**

. Click 

**Save**

. It replaces the group's price lists for everyone at the company. See 

[Give a company its own price list](https://docs.sparklayer.io/help/pricing/customer-pricing.md#give-a-company-its-own-price-list)

. 

[Take the 1-minute tour](https://docs.sparklayer.io/help/customers/companies?tour)

.

**For one customer:** add the price lists metafield to your store once, at **Integrations > Platform > Metafields** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Metafields** in the Shopify app (click **Configure** next to **SparkLayer metafields**). Then open the customer in your Shopify admin and enter the handle in their price lists metafield, for example `["acme-pricing"]`. Save the customer.

**BigCommerce and WooCommerce and Magento only:**

Enter the price list's handle in the customer's `price_lists` metafield (or attribute), for example `["acme-pricing"]`, and save the customer. Your developer or agency can set up the field: see [Give a customer their own price lists](https://docs.sparklayer.io/help/pricing/customer-pricing.md#give-a-customer-their-own-price-lists).

**Wix only:**

Wix doesn't support metafields, so customer pricing isn't available. Create a customer group for the account with its own price list, then add the group's label to the contact. See [Create a customer group](https://docs.sparklayer.io/help/customers/customer-groups.md#create-a-customer-group).

A customer's own price lists replace their group's price lists.

### Step 4. Add an extra percentage off

Optional. A customer discount takes an extra percentage off whatever prices the customer already gets.

**Shopify only:**

Enable the customer discount once at **Integrations > Platform > Metafields** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Metafields** in the Shopify app. Then open the customer in your Shopify admin and, in the **Metafields** card, enter the percentage in **Customer % Discount**, for example `25`. Save the customer.

**BigCommerce and WooCommerce and Magento only:**

Set the `discount_percentage` metafield (or attribute) on the customer, for example `25`. Your developer or agency can set up the field.

See [Give a customer an extra percentage discount](https://docs.sparklayer.io/help/pricing/customer-pricing.md#give-a-customer-an-extra-percentage-discount).

### Step 5. Check which price wins

Open the customer at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app. **Price list override** under **Basic information** and **Discount percentage** under **Financial details** show what's set on them.

If you've given a group or company more than one price list, order matters: SparkLayer uses the first list a SKU is in. See [How a buyer's price is chosen](https://docs.sparklayer.io/help/customers.md#how-a-buyers-price-is-chosen). [Take the 1-minute tour](https://docs.sparklayer.io/help/customers/managing-customers?tour).

## Check it worked

- **Sign in as someone at the account** and open a product on their price list. They see its price from that list, less any extra percentage.
- **Sign in as another buyer in the same group.** They still see the group's prices.
- **Search the SKU** at **Pricing > Price editor** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/editor)), or **SparkLayer Wholesale > Pricing > Price editor** in the Shopify app to compare its price in each list.

## If something's not right

- **They still see the group's prices.** Check the handle is typed exactly, inside square brackets and double quotes, and that the account has synced. See [Prices for one customer](https://docs.sparklayer.io/help/pricing/customer-pricing.md#give-a-customer-their-own-price-lists).
- **They see a price from the wrong list.** The SKU is in an earlier list on their group or company. See [Can I assign several price lists to one customer group or customer?](https://docs.sparklayer.io/help/pricing/faqs.md#can-i-assign-multiple-price-lists-to-one-customer-group-andor-customer)
- **A price is different from what you expect.** Your store prices may include tax. See [Prices are different from what you expect](https://docs.sparklayer.io/help/troubleshooting.md#prices-are-different-from-what-you-expect).
- **Checkout shows PRICING:001.** The account has price lists in 2 currencies. See [Customers see "An unknown error occurred" at checkout](https://docs.sparklayer.io/help/troubleshooting.md#customers-see-an-unknown-error-occurred-at-checkout).

## Next steps

- [Let trusted customers pay later on Net 30](https://docs.sparklayer.io/help/guides/net-terms.md): Give key accounts credit limits and payment terms
- [Run volume pricing and promotions](https://docs.sparklayer.io/help/guides/volume-discounts.md): Add price breaks, pack sizes and discounts
- [Set up wholesale prices](https://docs.sparklayer.io/help/guides/set-up-wholesale-prices.md): The price list and customer group everyone else uses


---

# Move brand discounts from another wholesale app

URL: https://docs.sparklayer.io/help/guides/migrate-brand-discounts
Applies to: Shopify

Recreate brand-by-brand trade discounts from another wholesale app in SparkLayer, with a manual price list per brand and a customer group per mix.

> **Quick summary**
>
> - You'll end up with each B2B customer getting the same discount on each brand as in your old wholesale app, for example 30% off Brand A and 20% off Brand B.
> - An automatic price list always applies to every product, so a discount on one brand needs a manual price list, built from a CSV of that brand's SKUs.
> - Customers who get the same mix of brand discounts share a customer group. Allow about an hour for a few brands, and longer if you have many combinations.
> - Price lists are on every plan. The free Basic plan includes 3 price lists, so you'll usually need Starter or above, which have unlimited price lists.

Some wholesale apps give a customer a percentage off a whole brand (the **Vendor** on a Shopify product). SparkLayer prices by SKU instead. You recreate each brand discount as a manual price list that holds the discounted price for every SKU of that brand, then give each customer the lists they need through their customer group.

How brand discounts become price lists:

1. **Product export**: Your Shopify products, filtered by vendor
2. **One price list per brand discount**: For example "Brand A 30%", uploaded by CSV
3. **One customer group per mix**: Holds each brand list the customers get, in order
4. **Customer tags**: `b2b` plus the group's tag

## Before you start

- **A list of your brand discounts**, from your old app: which customers get what percentage off which brand.
- **A unique SKU on every variant**, with each product **Active** and published to the **SparkLayer Wholesale** sales channel. Prices are matched to products by SKU.
- **Excel or Google Sheets**, to work out the prices.
- **The right plan** for the number of price lists you need. See [If you're on the Basic plan](https://docs.sparklayer.io/help/pricing/managing-pricing.md#if-youre-on-the-basic-plan).

## Set up your brand discounts

### Step 1. Work out your combinations

List each customer's brand discounts. Each brand and percentage becomes one price list. Each unique mix of price lists becomes one customer group, because a customer can only be in one group.

| Customer | Discounts in your old app | Price lists | Customer group |
| --- | --- | --- | --- |
| Retailer 1 | 30% off Brand A, 20% off Brand B | Brand A 30%, Brand B 20% | Brand A 30 + Brand B 20 |
| Retailer 2 | 30% off Brand A, 20% off Brand B | Brand A 30%, Brand B 20% | Brand A 30 + Brand B 20 |
| Retailer 3 | 25% off Brand A | Brand A 25% | Brand A 25 |

Retailers 1 and 2 share a group. Brand A needs two price lists, one at 30% and one at 25%.

### Step 2. Export your products from Shopify

In your Shopify admin, go to **Products** ([open in the Shopify admin](https://admin.shopify.com/products)), click **Export** and export all products as a CSV file. Open it in Excel or Google Sheets. Each variant has its own row, with its **Vendor**, **Variant SKU** and **Variant Price**.

### Step 3. Build a CSV for each brand discount

For each price list from step 1:

1. Filter the sheet by **Vendor** to show only that brand.
2. Copy the **Variant SKU** and **Variant Price** columns into a new sheet. Delete any rows with no SKU.
3. Add a column that works out the discounted price. For 30% off a price in column B, use `=ROUND(B2*(1-0.3),2)` and fill it down.
4. Keep two columns, headed `sku` and `price`, with the discounted prices as numbers only. Remove any spaces before or after the SKUs (the `TRIM` function does this).
5. Save the sheet as a CSV file, for example `brand-a-30.csv`.

**More detail**

- If your Shopify prices include tax, the discount is taken off the tax-inclusive price, so allow for tax when you work out your prices. See [Tax and VAT](https://docs.sparklayer.io/help/guides/tax-and-vat.md).
- The CSV format is in [Prepare your CSV file](https://docs.sparklayer.io/help/pricing/csv-upload.md#prepare-your-csv-file).

### Step 4. Create a manual price list for each brand discount

1. 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**.
2. Enter a **Name**, such as "Brand A 30%", and choose the **Currency**.
3. Tick **Enable manual pricing** and click **Save**.
4. Click **Upload** next to the new list, choose that brand's CSV file, check the rows under **Check your upload**, then click **Import**.

Repeat for each brand discount. See [Create a price list](https://docs.sparklayer.io/help/pricing/managing-pricing.md#create-a-price-list) and [Upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md).

### Step 5. Create a customer group for each combination

1. 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 click **Create customer group**.
2. Enter a **Name**, such as "Brand A 30 + Brand B 20", and click **Create group**. Note the group's tag, for example `b2b-brand-a-30-brand-b-20`.
3. Open the group and, under **Price lists**, add each of its brand price lists. Click **Add price list** for each one.
4. Click **Save**.

**Products from other brands**

A customer only gets prices for SKUs in their group's price lists, so products from brands with no discount show as **Unavailable**. To sell those at another price, add a list that covers them last, for example an automatic list at 0% off your Shopify prices. Price lists are used in order: SparkLayer uses the first list on the group that contains the SKU, so the brand lists must come before the catch-all list. See [Which price list wins](https://docs.sparklayer.io/help/pricing/managing-pricing.md#price-list-order).

### Step 6. Tag your customers

In your Shopify admin, open each customer and give them the tag `b2b` plus their group's tag, for example `b2b-brand-a-30-brand-b-20`. Save the customer. A customer can have no more than two B2B tags. See [Assign customers to a customer group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group).

## Add new products later

When you add products to a brand, export just the new products, work out their prices as in step 3, and upload a CSV with only the new SKUs to that brand's price list. Prices already on the list stay as they are.

## Check it worked

- **Sign in as a customer in each group**, or use [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order), and open a product from each brand. The price matches what they got in your old app.
- **Search a SKU** at **Pricing > Price editor** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/editor)), or **SparkLayer Wholesale > Pricing > Price editor** in the Shopify app to see its price in each list.
- **Open a product from a brand with no discount.** It shows the price from your catch-all list, or **Unavailable** if you didn't add one.

## If something's not right

- **A product shows Unavailable.** Its SKU isn't in any of the group's price lists, or the upload didn't match it. See [Why a product shows Unavailable](https://docs.sparklayer.io/help/pricing/managing-pricing.md#unavailable).
- **The upload worked but nothing matched.** The SKUs probably have spaces before or after them. See [The upload worked, but products show as Unavailable](https://docs.sparklayer.io/help/pricing/csv-upload.md#unavailable-after-upload).
- **A product gets the wrong brand's discount.** The SKU is in more than one of the group's lists, and the first one wins. Check the vendor filter in your CSV files and the order of the lists on the group.
- **A customer sees the Base group's prices.** Check they have both the `b2b` tag and their group's tag.
- **Prices are a little off.** Your Shopify prices may include tax. See [Prices are different from what you expect](https://docs.sparklayer.io/help/troubleshooting.md#prices-are-different-from-what-you-expect).

## Next steps

- [Price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md): Manage, clear and reorder your price lists
- [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md): Payment methods, order limits and other rules for each group
- [Run volume pricing and promotions](https://docs.sparklayer.io/help/guides/volume-discounts.md): Add price breaks, pack sizes and discounts


---

# How payments work

URL: https://docs.sparklayer.io/help/guides/how-payments-work
Applies to: Shopify

Follow Pay Online by Card, Pay by Invoice and Pay on Account from checkout to payment on Shopify, and choose which to offer each customer group.

> **Quick summary**
>
> - SparkLayer has 3 payment methods. With **Pay Online by Card**, the customer pays at the Shopify checkout. With **Pay by Invoice** and **Pay on Account**, they order now and pay you later.
> - You choose the methods for each customer group in its **Payment methods** rule at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app.
> - Pay-later orders arrive in Shopify as draft orders, or as unpaid orders if **Auto-complete draft orders** is on. Card orders arrive paid.
> - [SparkLayer Invoices](https://docs.sparklayer.io/help/ordering/invoices.md) needs the Growth plan or above. The [Xero](https://docs.sparklayer.io/help/integrations/accountancy/xero.md) and [QuickBooks Online](https://docs.sparklayer.io/help/integrations/accountancy/quickbooks.md) integrations need Pro or above.

Every B2B order is paid one of 3 ways. In the guide below, pick the options you use, such as how you send invoices or whether a customer has a credit limit, and each flow shows what the customer, SparkLayer, Shopify and your accounting software do.

**Interactive guide: how payments work** ([open the interactive guide](https://docs.sparklayer.io/guides/payment-methods/index.html)). For each of the 3 payment methods, a flow you can change shows each step from checkout to payment, with how to set it up, a credit limit example and which set-up suits which customers. The same information is in the sections below and the pages they link to.

## The 3 payment methods

Customers choose a method on the **Review & Pay** step of the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md), from the methods their customer group allows. A company or location with **Let them pay later** off can only pay by card. Quotes aren't a payment method: with the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md), the customer chooses how to pay when they complete the quote.

| Payment method | Pay Online by Card | Pay by Invoice | Pay on Account |
| --- | --- | --- | --- |
| **The customer pays** | At the Shopify checkout | After you invoice them | By their due date, for example Net 30 |
| **The order arrives in Shopify as** | A paid order | A draft order, or an unpaid order with auto-complete on | A draft order with payment terms, or an unpaid order with auto-complete on |
| **In the customer group rule** | **Card at checkout** | **Pay by invoice** | **Payment on account** |

### Pay Online by Card

The customer pays in full at your Shopify checkout, and the order arrives paid. In SparkLayer, card is simply on or off for each customer group. When a sales rep [orders for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#how-the-order-and-payment-work) and chooses card, the customer is emailed a link to pay.

### Pay by Invoice

The customer orders without paying, and you invoice them. Send the invoice from the Shopify draft order, with [SparkLayer Invoices](https://docs.sparklayer.io/help/ordering/invoices.md), or through [Xero or QuickBooks Online](https://docs.sparklayer.io/help/integrations/accountancy.md). Shopify's **Send invoice** is only on draft orders, so use it with **Auto-complete draft orders** off. See [Choose how to send invoices](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md#choose-how-to-send-invoices).

### Pay on Account

The customer orders within their credit limit and pays on their net terms. You set both on the customer, in the **Credit Limit and Account Balance** metafield. By default, Pay on Account is turned off for an order over the credit limit. With Xero, payments on the invoice reduce the customer's balance automatically; QuickBooks Online doesn't send payments back. See [Credit limits and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md).

## Next steps

- [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md): Choose each group's methods, and rename or reorder them at checkout
- [Let trusted customers pay later on Net 30](https://docs.sparklayer.io/help/guides/net-terms.md): Set up Pay on Account with credit limits and payment terms
- [Process your B2B orders in Shopify](https://docs.sparklayer.io/help/guides/process-orders-in-shopify.md): Complete drafts, take payment and send invoices


---

# Let trusted customers pay later on Net 30

URL: https://docs.sparklayer.io/help/guides/net-terms

Let trusted B2B customers order now and pay later: turn on Pay on Account for their group, set credit limits and Net 30 terms, and choose how to invoice.

> **Quick summary**
>
> - You'll end up with trusted customers who can choose **Pay on Account** at checkout, within a credit limit, on terms such as Net 30. They see their balance, limit and terms in My Account.
> - Allow about 30 minutes, plus a minute for each customer you give terms to.
> - Pay on Account, credit limits and net terms are on every plan. [SparkLayer Invoices](https://docs.sparklayer.io/help/ordering/invoices.md) needs the Growth plan or above.
> - Works on every platform. Credit limits and terms live in a customer [metafield](https://docs.sparklayer.io/help/glossary.md#metafields); on Shopify, SparkLayer adds it for you.

[Net terms](https://docs.sparklayer.io/help/glossary.md#net-terms) are the number of days a customer has to pay for an order they didn't pay for at checkout, such as 30 days on Net 30. There are 2 ways to pay later. **Pay on Account** charges the order to the customer's account, within their credit limit and on their net terms. **Pay by Invoice** lets them order without payment details, and you invoice them. Credit limits only apply to Pay on Account. See [Which method to offer](https://docs.sparklayer.io/help/ordering/payment-methods.md#which-method-to-offer). 

## Before you start

- **Which customers get terms**, their credit limits and their terms, such as Net 30.
- **How you'll invoice them**: SparkLayer Invoices, your store, your own invoice files or an app. See [Choose how to send invoices](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md#choose-how-to-send-invoices).
- **Access to edit customers** in your store admin, where the terms are stored.

## Set it up

### Step 1. Put trusted customers in their own group

Optional, but it keeps card-only customers separate. 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, click **Create customer group**, name it, for example "Trade 30 days", and add the customers to it. See [Create a customer group](https://docs.sparklayer.io/help/customers/customer-groups.md#create-a-customer-group).

### Step 2. Turn on Pay on Account for the group

Open the group, click **Override** next to **Payment methods** (on the Base group, **Customize**), tick **Payment on account** and click **Save**. Keep **Card at checkout** ticked if they can also pay by card.

See [Choose which payment methods a customer group can use](https://docs.sparklayer.io/help/ordering/payment-methods.md#choose-which-payment-methods-a-customer-group-can-use). [Take the 1-minute tour](https://docs.sparklayer.io/help/customers/customer-groups?tour).

### Step 3. Add the payment on account metafield

Credit limits, balances and net terms all live in one customer metafield, **Credit Limit and Account Balance** (`sparklayer.payment_on_account`). You add it once.

**Shopify only:**

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. In the **Metafields** card, click **Configure** next to **SparkLayer metafields** and enable it. See [Add metafields automatically](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#add-metafields-automatically).

**BigCommerce and Wix and WooCommerce and Magento only:**

Ask your developer to add it, using the settings in [The payment on account metafield](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md#the-payment-on-account-metafield) and the [developer docs](https://docs.sparklayer.io/developers.md).

### Step 4. Set each customer's credit limit and terms

Fill in the form with the customer's limit and terms, and copy the value it writes. For a 1,000 credit limit on Net 30, it's `{"credit_limit":1000,"net_terms":"30_days"}`. Then open the customer in your store admin, paste the value into the metafield and save.

**Lots of customers? Fill them in one table (Shopify):** in your Shopify admin, go to **Customers**, tick the customers and click **Edit customers**. Click **Columns**, tick **Credit Limit and Account Balance** under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

Terms can be 7, 15, 30, 45, 60 or 90 days. To add an opening balance, or a currency, see [Set a credit limit and account balance](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md#set-a-credit-limit-and-account-balance) and [Set net payment terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md#set-net-payment-terms).

**Example: $250 to spend**

Available credit is the `credit_limit` minus the `balance`, which is what the customer owes you. To give them $250 to spend, enter `{"credit_limit":250,"balance":0}`. After a $77.80 Pay on Account order, the balance is 77.80 and they have $172.20 left. Don't set `balance` to 250: that means they've already used it all. See [Worked example](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md#worked-example).

**More detail**

By default, a customer can't pay on account for an order over their credit limit. To allow it, see [Let customers order over their credit limit](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md#let-customers-order-over-their-credit-limit).

### Step 5. Decide what happens to their orders

**Shopify only:**

Pay on Account orders arrive in Shopify as draft orders, with **Payment terms** and a due date filled in, such as "Payment due on 19 June 2023 (Net 30)". To complete them automatically and collect payment later, turn on **Auto-complete draft orders** at **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app. See [Process your B2B orders in Shopify](https://docs.sparklayer.io/help/guides/process-orders-in-shopify.md).

**BigCommerce and Wix and WooCommerce and Magento only:**

Orders are placed without payment details, and you collect payment later. On Wix, they arrive with a payment status of "UNPAID": mark them as paid once you've been paid. See [How orders arrive in your store](https://docs.sparklayer.io/help/ordering/payment-methods.md#how-orders-arrive).

### Step 6. Choose how to send invoices

To let customers download a PDF invoice from My Account, turn on **Invoices** at **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app (Growth plan and above). Add your bank details with **Invoice Settings**. See [Turn on invoices](https://docs.sparklayer.io/help/ordering/invoices.md#turn-on-invoices). [Take the 1-minute tour](https://docs.sparklayer.io/help/dashboard/settings?tour).

An invoice is created once the order reaches **Processing**, so draft orders get one when they're completed. For other ways to invoice, see [Choose how to send invoices](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md#choose-how-to-send-invoices).

## Check it worked

- **In SparkLayer**, open the customer at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app. Under **Financial details**, **Payment on account** shows their **Credit limit** and **Net terms**.
- **In My Account**, signed in as the customer, **Financials** shows their balance, credit limit and payment terms.
- **At checkout**, **Pay on Account** is offered. Place a small test order with it.
- **In your store**, the order arrives unpaid, with its terms. On Shopify, it's a draft order with **Payment due later** ticked.

## If something's not right

- **Only card payment shows at checkout.** Check the group allows **Payment on account**. On Shopify, a company with **Let them pay later** off can only pay by card. See [Payment methods](https://docs.sparklayer.io/help/customers/customer-groups.md#choose-payment-methods) and [Paying](https://docs.sparklayer.io/help/customers/companies.md#paying).
- **Pay on Account is blocked for a customer you've just given credit.** Check their `balance` is 0, not the same as their limit. See [Worked example](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md#worked-example).
- **Pay on Account disappears for a large order.** The order would take them over their credit limit. See [What happens when a customer goes over their credit limit?](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md#what-happens-when-a-customer-goes-over-their-credit-limit)
- **The balance in the metafield doesn't change.** That's expected: SparkLayer works out the live balance itself. See [Why is the "Payment on Account" metafield not updating?](https://docs.sparklayer.io/help/ordering/payment-methods.md#why-is-the-payment-on-account-metafield-not-updating)
- **An order has no invoice.** Draft orders and orders awaiting approval get one once they're completed. See [When invoices are available](https://docs.sparklayer.io/help/ordering/invoices.md#when-invoices-are-available).

## Next steps

- [How payments work](https://docs.sparklayer.io/help/guides/how-payments-work.md): Follow each payment method from checkout to payment
- [Process your B2B orders in Shopify](https://docs.sparklayer.io/help/guides/process-orders-in-shopify.md): Complete drafts, take payment and send invoices
- [Give a key account their own prices](https://docs.sparklayer.io/help/guides/key-account-prices.md): Set different prices for your best customers
- [Get B2B tax and VAT right](https://docs.sparklayer.io/help/guides/tax-and-vat.md): Make sure tax is charged once, at checkout


---

# Process your B2B orders in Shopify

URL: https://docs.sparklayer.io/help/guides/process-orders-in-shopify
Applies to: Shopify

Find SparkLayer orders in Shopify, review and complete draft orders, take payment or mark them as paid, automate the routine parts and give buyers invoices.

> **Quick summary**
>
> - You'll end up with a routine for every B2B order: card orders arrive paid, and pay-later orders arrive as Shopify draft orders that you review, complete and get paid for.
> - Allow about 20 minutes to set up, then a minute or two per order. Automation can take most of that away.
> - Draft orders and auto-complete are on every plan. [SparkLayer Invoices](https://docs.sparklayer.io/help/ordering/invoices.md) needs the Growth plan or above. [Shopify Flow](https://docs.sparklayer.io/help/platforms/shopify/customisations/flow.md) is a free Shopify app, on every Shopify plan.

How an order arrives depends on how the buyer pays. Card orders go through the Shopify checkout and arrive paid. **Pay on Account** and **Pay by Invoice** orders arrive as [draft orders](https://help.shopify.com/en/manual/orders/create-orders), so you can change them before you take payment and fulfil.

## Before you start

- **Your customer groups' payment methods set.** See [Choose which payment methods a customer group can use](https://docs.sparklayer.io/help/ordering/payment-methods.md#choose-which-payment-methods-a-customer-group-can-use).
- **Access to Orders in your Shopify admin**, including **Drafts**.
- **A test order** to work through, for example one placed with [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order) using **Pay by Invoice**.

## Handle an order

### Step 1. Find the order

| The buyer chose | Where the order is |
| --- | --- |
| **Pay Online by Card** | In your Shopify **Orders**, paid. |
| **Pay on Account** or **Pay by Invoice** | In **Orders > Drafts** ([open in the Shopify admin](https://admin.shopify.com/draft_orders)). In SparkLayer, it shows as **Awaiting merchant** until it's completed. |
| **Pay Online by Card**, chosen by a sales agent or a company user | In **Drafts**. Shopify emails the buyer to complete payment. |
| **Pay Online by Card**, but the buyer left the checkout before paying | In **Drafts**, with no payment taken. Send the invoice or follow up with the buyer. |

Every B2B order has the `b2b` tag, so you can filter by it. See [How orders arrive in your store](https://docs.sparklayer.io/help/ordering/payment-methods.md#how-orders-arrive).

### Step 2. Get told about new draft orders

Shopify doesn't notify you about new draft orders. Set up an email alert with Shopify Flow, so someone knows to review each one. See [Get email alerts for new draft orders](https://docs.sparklayer.io/help/ordering/automation-and-workflows.md#get-email-alerts-for-new-draft-orders).

### Step 3. Review the draft order

Open the draft and change anything you need before you complete it, such as quantities or the shipping cost. To change shipping, see [Change shipping costs after an order is placed](https://docs.sparklayer.io/help/ordering/shipping-rules.md#change-shipping-costs-after-an-order-is-placed-on-shopify).

### Step 4. Complete it and take payment

Choose how you'll be paid:

| To | Do this in the draft order |
| --- | --- |
| **Send the buyer a payment link** | Send the invoice. The buyer gets an email with a **Complete your purchase** button. When they pay, the order moves to **Orders**, marked as paid. Click **Resend invoice** if they haven't paid. |
| **Record a payment you've taken another way** | Use **Collect payment** to mark it as paid. |
| **Give the buyer time to pay** | Add payment terms. Pay on Account orders arrive with their terms already filled in. |

See [Send invoices from your store](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md#send-invoices-from-your-store) and Shopify's guide to [accepting payment](https://help.shopify.com/en/manual/orders/create-orders#accept-payment).

### Step 5. Automate the routine parts

Optional. If you don't need to change orders before completing them:

- **Complete drafts automatically:** turn on **Auto-complete draft orders** at **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app and click **Save**. See [Complete draft orders automatically](https://docs.sparklayer.io/help/ordering/automation-and-workflows.md#complete-draft-orders-and-mark-them-as-paid-automatically). [Take the 1-minute tour](https://docs.sparklayer.io/help/integrations/managing-integrations?tour).
- **Mark orders as paid automatically:** import our **Mark order as paid** or **Mark Payment on Account order as paid** workflow into Shopify Flow. See [Order workflows](https://docs.sparklayer.io/help/platforms/shopify/customisations/flow.md#order-workflows).

> **Auto-completed orders can't be edited**
>
> Because of a Shopify limitation, orders completed by **Auto-complete draft orders** can't be edited afterwards. Shopify shows "Unable to edit order".

### Step 6. Give the buyer their invoice

With **Invoices** on at **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app, SparkLayer creates a PDF invoice once the order reaches **Processing**. The buyer downloads it with **View & Download Invoice** on the order in My Account. Draft orders get one when they're completed. See [Invoices](https://docs.sparklayer.io/help/ordering/invoices.md) and [When invoices are available](https://docs.sparklayer.io/help/ordering/invoices.md#when-invoices-are-available).

Then fulfil the order in Shopify as you would any other.

## Check it worked

Work through your test order:

- **It's in Orders > Drafts**, and shows as **Awaiting merchant** at **Orders** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/activity)), or **SparkLayer Wholesale > Orders** in the Shopify app. [Take the 1-minute tour](https://docs.sparklayer.io/help/dashboard/orders?tour).
- **Once you complete it**, it moves to your Shopify **Orders**.
- **In the buyer's My Account**, its status changes from "Awaiting merchant", for example to "Processing", and **View & Download Invoice** appears if invoices are on.

## If something's not right

- **An order isn't in your Shopify orders.** It's probably a draft. See [Orders don't show in your Shopify orders](https://docs.sparklayer.io/help/troubleshooting.md#orders-dont-show-in-your-shopify-orders).
- **Shopify says "Unable to edit order".** The order was auto-completed. See "Can I edit orders?" in [Shopify FAQs](https://docs.sparklayer.io/help/platforms/shopify/faqs.md#orders).
- **The buyer sees "Awaiting merchant".** That's expected until you complete the draft. See [Orders show as "Awaiting merchant"](https://docs.sparklayer.io/help/troubleshooting.md#orders-show-as-awaiting-merchant).
- **The buyer can't download an invoice.** See [I can't download an invoice](https://docs.sparklayer.io/help/ordering/invoices.md#i-cant-download-an-invoice-what-am-i-doing-wrong).

## Next steps

- [Let trusted customers pay later on Net 30](https://docs.sparklayer.io/help/guides/net-terms.md): Set credit limits and payment terms
- [Charge the right B2B shipping](https://docs.sparklayer.io/help/guides/b2b-shipping.md): Set B2B shipping methods and costs
- [Get B2B tax and VAT right](https://docs.sparklayer.io/help/guides/tax-and-vat.md): Make sure tax on orders is right


---

# Show imported or manual orders in My Account

URL: https://docs.sparklayer.io/help/guides/show-imported-orders
Applies to: Shopify

Show orders created outside the SparkLayer checkout, such as Shopify draft orders or imported history, in My Account with a tag and an order metafield.

> **Quick summary**
>
> - You'll end up with orders you created in the Shopify admin, or imported from another system, showing in your customers' order history in My Account.
> - Allow about 10 minutes for a few orders. For hundreds, allow longer and use an import app such as Matrixify.
> - Everything in this guide is for Shopify. On BigCommerce, see [Import past orders](https://docs.sparklayer.io/help/platforms/bigcommerce/metafields.md#import-past-orders).

[My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) only shows orders placed through the SparkLayer checkout. An order created another way, such as a draft order you made in the Shopify admin or a historic order you imported, needs 2 things before it shows: the `b2b` order tag, and the **B2B - Order Import** order metafield set to `true`.

## Before you start

- **SparkLayer installed** on your store. Set orders up after installing, so they sync.
- **Each order belongs to the B2B customer** who should see it.
- **A list of the orders** to show, with their Shopify order numbers.

## Show the orders

### Step 1. Add the order import metafield

The order metafield `sparklayer.order_import` must exist before you can fill it in. In Shopify, go to **Settings > Custom data** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data)), click **Orders** and check for **B2B - Order Import**. If it isn't there, click **Add definition** and enter:

| Field | Value |
| --- | --- |
| **Namespace and key** | `sparklayer.order_import` |
| **Type** | True or false (`boolean`) |

See [Import order history into SparkLayer](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#import-order-history-into-sparklayer).

### Step 2. Tag the orders `b2b`

For one order, open it in **Orders** ([open in the Shopify admin](https://admin.shopify.com/orders)), add the tag `b2b` under **Tags** and save.

For many, tick the orders in **Orders** ([open in the Shopify admin](https://admin.shopify.com/orders)), click **Add tags**, enter `b2b` and save.

### Step 3. Set the metafield to true

For one order, open it in Shopify and, in its **Metafields** card, set **B2B - Order Import** to `true`. Click **Show all** if you can't see it. Save the order.

**For many orders, use Matrixify**

An import app such as [Matrixify](https://apps.shopify.com/excel-export-import) sets the metafield on many orders at once. Start from our [sample CSV template](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/example-historic-order-import.csv?v=1738672207), or put each Shopify order ID in the `ID` column:

| ID | Metafield: sparklayer.order\_import \[boolean] | Command |
| --- | --- | --- |
| `[order-id-here]` | `TRUE` | `UPDATE` |

## Check it worked

- **In SparkLayer**, the orders show at **Orders** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/activity)), or **SparkLayer Wholesale > Orders** in the Shopify app.
- **In My Account**, signed in as the customer, the orders show in **Recent Activity**.
- **In Shopify**, each order has the `b2b` tag and **B2B - Order Import** is `true`.

## If something's not right

- **The order doesn't show.** Check it has both the `b2b` tag and the metafield set to `true`. One without the other isn't enough.
- **You can't find B2B - Order Import on the order.** The metafield definition doesn't exist yet. Add it as in step 1, then set the value.
- **A draft order you created still doesn't show.** Draft orders aren't listed in My Account until they're completed. Complete it in Shopify first. See [Complete a draft order by hand](https://docs.sparklayer.io/help/ordering/automation-and-workflows.md#complete-a-draft-order-by-hand).

## Next steps

- [Move your existing wholesale customers onto SparkLayer](https://docs.sparklayer.io/help/guides/move-existing-customers.md): Bring across customers, their terms and their order history
- [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md): What customers see in their order history
- [Shopify metafields and data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md): Every SparkLayer metafield, and how to fill them in bulk


---

# Keep wholesale prices and products hidden from retail shoppers

URL: https://docs.sparklayer.io/help/guides/hide-wholesale-from-retail
Applies to: Shopify

Hide B2B-only products from retail shoppers with B2B Catalogs, hide prices from signed-out visitors, or make everyone sign in before they see your store.

> **Quick summary**
>
> - You'll end up with retail shoppers and signed-out visitors seeing only what's meant for them, while signed-in B2B customers see your full wholesale range and prices.
> - Allow about 30 minutes for B2B Catalogs. Hiding prices or locking the store is a theme code change, so allow time for your developer.
> - [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md) is a free app on every SparkLayer plan. Everything in this guide is for Shopify.

Retail and B2B customers can share one Shopify store. SparkLayer only shows B2B prices to signed-in B2B customers, but your products and Shopify prices are visible to everyone until you hide them.

## Before you start

- **Your B2B customers tagged `b2b`** in Shopify. See [Assign customers to a customer group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group).
- **A list of B2B-only products**, and any that should be retail-only.
- **Someone who can edit your theme code**, if you'll hide prices or lock the store. We can explain the approach, but we can't make the changes for you.

## Hide what retail shoppers shouldn't see

### Step 1. Choose what to hide

| To hide | Use | How |
| --- | --- | --- |
| **Products** from retail customers, or from B2B customers | B2B Catalogs (steps 2 to 4) | Tags in your Shopify admin, no code |
| **Prices** from signed-out visitors | Liquid code in your theme (step 5) | A developer change |
| **Your whole store** until a customer signs in | Liquid code in your theme (step 6) | A developer change |

You can use any of them together. See [B2B Catalogs or B2B-only content](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md#b2b-catalogs-or-b2b-only-content).

### Step 2. Install and enable B2B Catalogs

Install [B2B Catalogs](https://apps.shopify.com/sparklayer-b2b-catalogs) from the Shopify App Store. Open it in your Shopify admin and, under **Enable on your theme**, choose your theme and click **Enable**. See [Install and enable B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md#install-and-enable-b2b-catalogs).

### Step 3. Tag your B2B-only products

In your Shopify admin, open each product and add the tag `b2b-only`, then save. Use `b2c-only` for products only retail customers should see. Products with neither tag are shown to everyone. See [Make a product B2B-only or B2C-only](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-your-catalogs.md#make-a-product-b2b-only-or-b2c-only).

A hidden product disappears from product pages, collection pages and store search. If someone opens its URL directly, they see an access denied page, which you can change: see [Customise the access denied page](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-access-denied-view.md).

### Step 4. Hide products from some customer groups

Optional. To show a range to one customer group only, hide its variants from the other groups with the `sparklayer.settings` variant metafield. This needs the SparkLayer Wholesale app as well as B2B Catalogs. Tag the products `b2b-only` too if retail shoppers shouldn't see them. See [Catalogs per customer group](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-advanced-catalogs.md), and the [worked example](https://docs.sparklayer.io/help/storefront/product-settings.md#example-a-product-range-for-each-customer-group). [Hide products from customers](https://docs.sparklayer.io/help/guides/hide-products.md) has a form that writes the rule, and your AI assistant can apply it.

Variant rules only apply to B2B customer groups: they don't hide anything from retail shoppers, and Shopify can't hide a single variant from them. To keep one variant for B2B customers only, make it a separate product and tag it `b2b-only`: see [Sell a B2B-only version of a product](https://docs.sparklayer.io/help/guides/sell-b2b-only-versions.md).

### Step 5. Hide prices from signed-out visitors

Optional. Ask your developer to add the example code to your product cards and product page. Signed-in B2B customers see the SparkLayer product card, and everyone else sees "Please sign in to see pricing". See [Hide prices from signed-out visitors](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-only-content.md#hide-prices-from-signed-out-visitors).

### Step 6. Make customers sign in first

Optional, for a store that's only for trade customers. Ask your developer to add the redirect code to `theme.liquid`. Signed-out visitors go to the login page, except on pages you leave open, such as `/pages/b2b-login`. See [Make customers sign in before they see your store](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md#make-customers-sign-in-before-they-see-your-store).

## Check it worked

- **Signed out, in a private browser window:** B2B-only products don't appear in collections or search, opening one's URL shows the access denied page, and prices are hidden if you added that code.
- **Signed in as a B2B customer:** you see the B2B-only products with your trade prices, and not the `b2c-only` ones.
- **Signed in as a customer in another group:** products you've hidden from that group don't appear.

## If something's not right

- **B2B Catalogs can't change your theme.** The theme has invalid Liquid syntax. See [Invalid Liquid syntax](https://docs.sparklayer.io/help/storefront/b2b-catalogs/limitations.md#invalid-liquid-syntax).
- **A retail shopper sees a B2B-only variant.** Variant rules don't apply to retail shoppers. Make the variant a separate `b2b-only` product. See [Variants and retail shoppers](https://docs.sparklayer.io/help/storefront/b2b-catalogs/limitations.md#variants-and-retail-shoppers).
- **A collection page has gaps, or its counts include hidden products.** Hiding happens as the page loads. See [Collection grids, search and filter counts](https://docs.sparklayer.io/help/storefront/b2b-catalogs/limitations.md#grids-search-and-filter-counts).
- **A hidden product is still in someone's cart.** Products already in a cart stay there. See [Hidden products in a cart](https://docs.sparklayer.io/help/storefront/b2b-catalogs/limitations.md#hidden-product-add-to-cart-caveats).
- **B2B-only products are in your sitemap.** Shopify's sitemap still lists them, but search engines can't see the pages. See [B2B Catalogs FAQs](https://docs.sparklayer.io/help/storefront/b2b-catalogs/faqs.md#visibility).
- **Your Shopify prices show in Google.** That's standard Shopify behaviour, not SparkLayer. See "How do I stop my Shopify prices showing in Google search results?" in [Shopify FAQs](https://docs.sparklayer.io/help/platforms/shopify/faqs.md#theme-and-storefront).

## Next steps

- [Let new trade customers apply](https://docs.sparklayer.io/help/guides/approve-trade-applications.md): Add a B2B login page and approve applications
- [Set up wholesale prices](https://docs.sparklayer.io/help/guides/set-up-wholesale-prices.md): Set the prices signed-in buyers see
- [B2B-only content](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-only-content.md): Show B2B-only menus, banners and content


---

# Hide products from customers

URL: https://docs.sparklayer.io/help/guides/hide-products
Applies to: Shopify, BigCommerce, WooCommerce, Magento

Hide products from B2B customers, some customer groups or retail shoppers: in Catalog and Quick Order, the cart and your store's pages, one product or hundreds.

> **Quick summary**
>
> - You'll end up with the products you choose hidden from the customers who shouldn't see them: every B2B customer, some customer groups or retail shoppers.
> - Most stores hide custom products that need artwork, printing charges and add-on fees, or a range kept for one customer group.
> - Allow about 15 minutes, plus a minute or so a product. A form on this page writes the setting for you, and your AI assistant can apply it to every product.

There are 2 places a product can show: in SparkLayer, where B2B customers and sales reps order, and on your store's own pages. You hide it from each in a different way. Most stores only need the first.

## Pick the right option

| You want to | Do this | Hidden in |
| --- | --- | --- |
| **Stop B2B customers seeing or ordering a product**, such as a custom product or a fee | Set `"display": false` in the product's `sparklayer.settings`, as on this page | SparkLayer: Catalog and Quick Order, search in My Cart and SparkLayer's product interfaces |
| **Keep it on show, but stop orders** | Set `"sell": false` instead | Nothing hidden: it can't be added to the cart |
| **Show a range to some customer groups only** | Hide it for everyone with a `base` entry, then show it to those groups | SparkLayer, for every other group |
| **Hide products from retail shoppers and signed-out visitors** | Tag them `b2b-only` with the free B2B Catalogs app (Shopify) | Your store's collection, search and product pages. See [Keep wholesale hidden from retail shoppers](https://docs.sparklayer.io/help/guides/hide-wholesale-from-retail.md) |
| **Hide a range from some customer groups on your store's pages too** | Combine the two: B2B Catalogs and `display` per customer group (Shopify) | SparkLayer and your store's pages. See [Catalogs per customer group](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-advanced-catalogs.md) |

**What each setting hides, in detail**

`display` and `sell` are 2 of the [product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md) in the `sparklayer.settings` metafield. They only apply to signed-in B2B customers, and to sales reps ordering for them. Retail shoppers see whatever your theme shows. See [What hides what](https://docs.sparklayer.io/help/storefront/product-settings.md#what-hides-what) for every view.

## Before you start

- **The products to hide**: their SKUs, or a way to find them, such as a tag like `CUSTOM`.
- **The customer groups**, if you're only hiding them from some. You need each group's handle, such as `trade`: click the group's name at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app.
- **Access to your store's admin**, to edit the products' variants.

## Hide the products

### Step 1. Turn on the metafield in SparkLayer

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 and, in the **Metafields** card, click **Configure** next to **SparkLayer metafields**, then enable the product settings metafield. You only do this once.

**More detail**

On Shopify, SparkLayer adds the `sparklayer.settings` field to every variant for you. On BigCommerce, WooCommerce and Magento, follow your platform's guide: [BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce/metafields.md), [WooCommerce](https://docs.sparklayer.io/help/platforms/woocommerce/metafields.md) or [Magento](https://docs.sparklayer.io/help/platforms/magento/metafields.md).

### Step 2. Build the setting

Choose who shouldn't see the products and whether to hide them or only stop orders. The form writes the value, which is the same for every product.

**What the values look like**

Hide from every B2B customer:

```json
[{ "customer_group": "base", "display": false, "sell": false }]
```

Hide from the `trade` and `distributors` groups only:

```json
[
  { "customer_group": "trade", "display": false, "sell": false },
  { "customer_group": "distributors", "display": false, "sell": false }
]
```

Show only to the `vip` group:

```json
[
  { "customer_group": "base", "display": false, "sell": false },
  { "customer_group": "vip", "display": true, "sell": true }
]
```

### Step 3. Add it to the products

The value goes in the `sparklayer.settings` field of every variant you're hiding: a product in 3 sizes needs it on all 3. Choose the way that suits how many there are.

| How many | How |
| --- | --- |
| **A few** | Open each variant in your store's admin, paste the value into its `sparklayer.settings` field and save. In Shopify, it's **Settings** under **Metafields**, as the form shows. |
| **Many** | Fill in the field for every variant in one table, in your platform's bulk editor. |
| **Many, or found by a tag** | Let your AI assistant do it. Connect your Shopify store to it, such as with the Shopify connector in Claude, then click **Ask Claude** or **Ask ChatGPT** in the form and tell it which products. It finds the variants, shows you every change and only saves them once you approve. |

**Lots of products? Fill them in one table (Shopify):** in your Shopify admin, go to **Products**, tick the products and click **Edit products**. Click **Columns**, tick the SparkLayer field under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

**If the products already have a value**

A variant can already have a `sparklayer.settings` value, such as a pack size for a customer group. Pasting a new value replaces it, so add the `display` and `sell` keys to the entries that are there instead. The AI assistant's prompt does this for you: it keeps every other setting.

### Step 4. Hide them from your store's pages too

Optional, on Shopify. To hide the same products from retail shoppers and signed-out visitors, tag them `b2b-only` with B2B Catalogs: see [Keep wholesale hidden from retail shoppers](https://docs.sparklayer.io/help/guides/hide-wholesale-from-retail.md). To hide them from some customer groups on your store's pages as well, see [Catalogs per customer group](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-advanced-catalogs.md).

## Check it worked

Changes take about 10 minutes to sync. Then check as each kind of customer:

| Check as | What you should see |
| --- | --- |
| **A customer in a group you hid them from** | The products aren't in [Catalog and Quick Order](https://docs.sparklayer.io/help/sales-ordering/catalog.md) or in search in My Cart. With **Show it, but stop orders**, they show as **Unavailable for this account**. |
| **A sales rep ordering for that customer** | The same as the customer: the rep's **Catalog** follows the customer's group. |
| **A customer in another group** | The products as usual. |

## If something's not right

- **A product still shows.** Check the value is on every variant, not the product, and that each `customer_group` is a handle, such as `trade`, not a Shopify tag, such as `b2b-trade`. See [Why aren't my settings being applied?](https://docs.sparklayer.io/help/storefront/product-settings.md#settings-not-applied)
- **A pack size or limit stopped working.** The new value replaced the variant's old one. Add the old settings back into the same value: see [Which rule wins](https://docs.sparklayer.io/help/storefront/product-settings.md#which-rule-wins).
- **The product still shows on your store's collection pages.** `display` only changes SparkLayer. Use B2B Catalogs as well: see [step 4](#hide-on-store-pages).
- **The value doesn't save.** It must be valid JSON with straight quotes (`"`). Build it with the [form](#build-the-setting) rather than typing it.

## Next steps

- [Catalog and Quick Order](https://docs.sparklayer.io/help/sales-ordering/catalog.md): How customers and reps browse and order from the catalog
- [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md): Pack sizes, limits and visibility for each customer group
- [Keep wholesale hidden from retail shoppers](https://docs.sparklayer.io/help/guides/hide-wholesale-from-retail.md): Hide B2B products and prices from retail shoppers


---

# Sell a B2B-only version of a product

URL: https://docs.sparklayer.io/help/guides/sell-b2b-only-versions
Applies to: Shopify

Sell a trade-only version of a retail product, such as a case of 12: duplicate it in Shopify, give it new SKUs, tag it b2b-only, price it and test it.

> **Quick summary**
>
> - You'll end up with a separate product, such as "Olive Oil, Case of 12", that only signed-in B2B customers can see and buy, at their trade price. Retail shoppers keep seeing the original.
> - It has to be its own product: Shopify can't hide a single variant from retail shoppers, and the `b2b-only` tag works on whole products.
> - Allow about 15 minutes a product. It needs [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md), a free app on every SparkLayer plan, and is for Shopify.

The `b2b-only` tag hides a whole product from retail shoppers. That works when a product is only ever sold to trade customers. When you sell the same item to both, in a different pack size or format for trade, the trade version needs its own product, with its own SKUs, so it can be tagged and priced on its own.

## Pick the right route

Not every B2B-only product needs a duplicate. Choose by what you want to do:

| You want to | Do this |
| --- | --- |
| **Show a whole existing product to B2B customers only** | No duplicate: tag the product `b2b-only`, then check [steps 5 and 6](#check-b2b-catalogs) below. See [Make a product B2B-only or B2C-only](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-your-catalogs.md#make-a-product-b2b-only-or-b2c-only) |
| **Sell a B2B version of a retail product**, such as a case of 12 alongside single bottles | Follow every step on this page |
| **Show a range to one customer group only**, such as VIP trade customers | No duplicate: hide it from the other groups with the `sparklayer.settings` metafield. See [Hide products from customers](https://docs.sparklayer.io/help/guides/hide-products.md) |

## Before you start

- **B2B Catalogs installed**, and enabled on the theme you'll test on. See [Install and enable B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md#install-and-enable-b2b-catalogs).
- **A B2B customer to test with**, tagged `b2b`, and a retail customer account. See [Assign customers to a customer group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group).
- **The trade price** for the new version, or the rule your price list uses for it.

## Create the B2B-only version

### Step 1. Duplicate the original product

In your Shopify admin, open the original product at **Products** ([open in the Shopify admin](https://admin.shopify.com/products)), then click **More actions** > **Duplicate**. Name the copy after the original plus its pack size or format, such as "Olive Oil, Case of 12", and copy the images. Set its status to **Draft**.

**More detail**

Keep it as a draft until it's tagged `b2b-only` in step 3. A product that goes live untagged shows to everyone, retail shoppers included.

### Step 2. Give every variant a new SKU

Open each variant of the copy and replace its SKU, so none is left the same as the original's. A simple pattern is the original SKU plus a suffix: `OIL-500` becomes `OIL-500-CASE12`. Then, under **Search engine listing**, remove `-copy` from the URL handle.

**More detail**

SparkLayer matches prices to products by SKU, so every variant needs a SKU of its own. If the copy shares a SKU with the original, the trade price lands on the wrong product or doesn't show at all. See [Do I need product SKUs when uploading pricing?](https://docs.sparklayer.io/help/pricing/faqs.md#do-i-need-product-skus-when-uploading-pricing)

### Step 3. Tag it b2b-only and make it active

Add the tag `b2b-only` in the product's **Tags** field. Change its status to **Active** and click **Save**.

Should B2B customers still see the retail version too? If not, tag the original `b2c-only`, so they only see the trade version.

### Step 4. Price it for your B2B customers

Do this once the product is **Active**: SparkLayer only syncs active products, so it can't price a draft. How depends on your price list:

| Price list | What to do |
| --- | --- |
| **Automatic** (for example 30% off your Shopify prices) | Nothing to add: it prices every product, including the new one. Check the price looks right |
| **Manual** (exact prices) | Add a price for each new SKU, with the [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md#add-a-price) or a [CSV upload](https://docs.sparklayer.io/help/pricing/csv-upload.md), in every price list your B2B customer groups use |

Then check the new SKUs' prices at **Pricing > Price editor** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/editor)), or **SparkLayer Wholesale > Pricing > Price editor** in the Shopify app.

### Step 5. Check B2B Catalogs is on your live theme

Open B2B Catalogs in your Shopify admin, and check your live theme shows as **Enabled**. Without it, the `b2b-only` tag does nothing: it's the most common reason a product still shows to retail shoppers.

**More detail**

If B2B Catalogs isn't installed yet, install it from the [Shopify App Store](https://apps.shopify.com/sparklayer-b2b-catalogs) and enable it on an unpublished copy of your theme first, to check it. See [Install and enable B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md#install-and-enable-b2b-catalogs).

### Step 6. Test it as three kinds of visitor

Check the product as each of these. All three must pass.

| Test as | Sees the product? | What you should see |
| --- | --- | --- |
| **A signed-out visitor**, in a private browser window | No | It's missing from collections and search. Its URL shows the [access denied page](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-access-denied-view.md) |
| **A signed-in retail customer** | No | The same as a signed-out visitor |
| **A signed-in B2B customer** | Yes | It's in collections and search, at the trade price from their price list |

## Common mistakes

**The trade price shows on the wrong product, or not at all**

A variant still has the SKU it was copied with. Check every variant of the copy, not just the first, and give each one its own SKU. See [step 2](#new-skus).

**The new product has no trade price**

Prices were added while the product was a draft, or it's on a manual price list without its new SKUs. Check the product is **Active**, then check its SKUs at **Pricing > Price editor** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/editor)), or **SparkLayer Wholesale > Pricing > Price editor** in the Shopify app. See [step 4](#price).

**Retail shoppers can still see the product**

Check the product is tagged `b2b-only`, and that B2B Catalogs is enabled on your live theme. See [step 5](#check-b2b-catalogs) and [Why don't my b2b-only and b2c-only tags do anything?](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md#tags-not-working).

**Can I tag just one variant b2b-only?**

No. Tags work on whole products, and Shopify can't hide a single variant from retail shoppers. If only one pack size is for trade customers, make it its own product, as on this page. See [Variants and retail shoppers](https://docs.sparklayer.io/help/storefront/b2b-catalogs/limitations.md#variants-and-retail-shoppers).

**What about stock?**

The new SKUs have their own inventory in Shopify. If the trade version comes from the same physical stock as the original, decide how you'll keep both counts right, for example by adjusting them when you restock.

## Good to know

- **Collection pages can show gaps.** A hidden product can still take a place in a collection grid, and count towards product and filter totals. Keeping B2B-only products in their own collections avoids it. See [Collection grids, search and filter counts](https://docs.sparklayer.io/help/storefront/b2b-catalogs/limitations.md#grids-search-and-filter-counts).
- **Hiding doesn't empty carts.** A product already in someone's cart stays there, and add-to-cart links still work. See [Hidden products in a cart](https://docs.sparklayer.io/help/storefront/b2b-catalogs/limitations.md#hidden-product-add-to-cart-caveats).

## Next steps

- [Keep wholesale hidden from retail shoppers](https://docs.sparklayer.io/help/guides/hide-wholesale-from-retail.md): Hide B2B products and prices from everyone but your trade customers
- [Catalogs per customer group](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-advanced-catalogs.md): Show a range to some customer groups only
- [Upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md): Add trade prices for many SKUs at once


---

# Let new trade customers apply, and approve them

URL: https://docs.sparklayer.io/help/guides/approve-trade-applications
Applies to: Shopify

Add a B2B login and registration page to your Shopify store, collect trade account applications with SparkLayer Forms, and approve each buyer into a group.

> **Quick summary**
>
> - You'll end up with a B2B login page where new customers apply for a trade account, and a list of applications you approve or reject. Approving one creates the customer in Shopify in the customer group you choose.
> - Allow about 45 minutes, or less if our team installs the B2B login page for you, free of charge.
> - [Forms](https://docs.sparklayer.io/help/forms.md) are on every plan, in the SparkLayer Dashboard only. The notification emails and the **Approve** and **Reject** buttons run on [workflows](https://docs.sparklayer.io/help/forms/workflows.md), which are on the Growth plan and above (see [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md)). Without them, you [approve applications by hand](https://docs.sparklayer.io/help/forms/entries.md#approve-an-application-without-workflows).

Customers who apply don't become B2B customers until you approve them. You check each application, choose their customer group, and SparkLayer creates and tags them for you. Forms are only in the SparkLayer Dashboard at [app.sparklayer.io](https://app.sparklayer.io/), not in the SparkLayer Wholesale app in Shopify admin.

## Before you start

- **Your customer groups set up**, so you can choose one when you approve. See [Set up wholesale prices](https://docs.sparklayer.io/help/guides/set-up-wholesale-prices.md).
- **A SparkLayer Dashboard login** at [app.sparklayer.io](https://app.sparklayer.io/), for Forms.
- **Customer accounts turned on** in your Shopify admin, at **Settings > Customer accounts** ([open in the Shopify admin](https://admin.shopify.com/settings/customer_accounts)).

## Set up applications

### Step 1. Create your registration form

In the SparkLayer Dashboard, go to **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)). On the **Start from a template** card, click **Wholesale Registration Form**. It comes with an approve and reject workflow and email notifications. See [Start from a template](https://docs.sparklayer.io/help/forms.md#start-from-a-template). [Take the 1-minute tour](https://docs.sparklayer.io/help/forms?tour).

Add or change fields if you need more from applicants. See [Build a form](https://docs.sparklayer.io/help/forms/setup.md).

### Step 2. Check who's told about new applications

The template's **Notification of submission** workflow emails your team about each new entry. To change the recipient, open the **Workflows** tab and click **View** next to it. See [Get notified of new submissions](https://docs.sparklayer.io/help/forms/setup.md#get-notified-of-new-submissions).

### Step 3. Publish the form

Click **Publish**. The form and its workflows only go live once you publish. See [Publish changes](https://docs.sparklayer.io/help/forms/versions.md#publish-changes).

### Step 4. Add the B2B login page

Our free, ready-made page lets existing customers sign in and new ones apply, at `/pages/b2b-login`. Adding it means creating 2 files in your theme code. [Contact us](https://docs.sparklayer.io/help/support.md) and our team installs it for you, or follow [Add the B2B login page](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md#add-the-b2b-login-page).

### Step 5. Put your form on the page

In the theme editor, open the `b2b-login` page and set **Form Action** to **Embed custom contact form**. Paste your form's embed code, from its **Embed** tab, into **Custom Contact Form HTML**, then save. See [Embed a SparkLayer form](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md#embed-a-sparklayer-form).

**More detail**

- To show the form on another page instead, add the **SparkLayer Form** block in the theme editor. See [Add a form to your store](https://docs.sparklayer.io/help/forms/embedding-and-styling.md#add-a-form-to-your-store).
- To share it as a link, click **Copy registration link** on the form's **Embed** tab, or in the **Invite a buyer** box. See [Share your registration link](https://docs.sparklayer.io/help/customers/invite-buyers.md#share-your-registration-link).

### Step 6. Approve or reject each application

Open the form's entries and click the applicant's name. Under **Your decision**, choose their **Customer group**, tick **Tax exempt** if they shouldn't pay tax, then click **Approve** or **Reject**.

Approving creates the customer in Shopify with the group's tag and emails them. They can sign in and see trade prices straight away. See [Approve or reject an application](https://docs.sparklayer.io/help/forms/entries.md#approve-or-reject-an-application).

**Not using SparkLayer Forms?**

The B2B login page can instead email applications to your store's email address, through Shopify's contact form. Sending it doesn't create a customer. Once you've reviewed it, add them to a customer group by [tagging them in Shopify](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group), or invite them with **Invite buyer** at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app and choose their customer group. See [Send an email to the store owner](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md#send-an-email-to-the-store-owner) and [Invite a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md).

## Check it worked

- **Apply as a customer.** Go to `www.yourstore.com/pages/b2b-login` and send an application with an email address you can sign in to.
- **Find the entry.** It's in the form's entries, and your team gets the notification email.
- **Approve it.** The new customer shows at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app in the group you chose. [Take the 1-minute tour](https://docs.sparklayer.io/help/customers/managing-customers?tour).
- **Sign in as them.** You see your trade prices.

## If something's not right

**Diagnose: Trade applications not working?** Check your form, approvals and customer sign-in.

1. **What’s going wrong?** Pick the closest match.
   - Customers can’t find the application form: go to question 2
   - I’m not told about new applications: go to question 2
   - Approve or Reject on an entry does nothing: go to fix A (Approve and Reject run on workflows)
   - Approved customers can’t see B2B pricing: go to question 2
   - Approved customers didn’t get an email: go to question 2
   - People sign in without applying: go to fix B (Shopify lets anyone create an account)
   - Customers can’t sign in: go to question 3
2. **Which form do you use for applications?** SparkLayer Forms is built into the SparkLayer Dashboard. Customer Fields is a separate Shopify app.
   - SparkLayer Forms: go to question 4 for missing; question 5 for arriving; question 6 for access; question 7 for email
   - Customer Fields: go to question 8 for missing; question 9 for arriving; question 10 for access; question 11 for email
   - Another app: go to fix C (Check your form app’s settings)
3. **Which customer accounts does your Shopify store use?** Shopify has customer accounts (sign in with an emailed code) and legacy accounts (sign in with a password). Where to look: Settings > Customer accounts (Shopify admin).
   - Customer accounts (a code): go to fix D (Sign in with the code, using the right email)
   - Legacy accounts (a password): go to fix E (The customer needs to activate their account)
   - Not sure: go to fix F (Check your customer accounts setting)
4. **Is the form added to a page on your live theme?** Forms are built in SparkLayer, then added to a page on your store. Where to look: Forms (SparkLayer).
   - Yes: go to question 12
   - No / not sure: go to fix G (Add the form to a page)
5. **Do new submissions show on the form’s Entries tab?** Applications appear there as soon as they’re submitted. Where to look: Forms (SparkLayer).
   - Yes: go to fix H (Applications are arriving: add a notification)
   - No: go to question 4
6. **Does approving an application give the customer the `b2b` tag and their group’s tag?** The Wholesale Registration Form template creates the customer with their customer group’s tag when you approve them. Where to look: Forms (SparkLayer).
   - Yes: go to fix I (Approval looks right: check the customer)
   - No / not sure: go to fix J (Check what approval does)
7. **Does the form’s approval workflow send the customer an email?** Emails to customers are sent by a workflow step. Where to look: Forms (SparkLayer).
   - Yes: go to fix K (Check the email arrived)
   - No / not sure: go to fix L (Add an email step to the approval workflow)
8. **Is Customer Fields turned on in your theme, with the form on a page?** The app must be enabled in the theme editor and its form added to a page. Where to look: Online Store > Themes (Shopify admin).
   - Yes: go to question 12
   - No / not sure: go to fix M (Turn on Customer Fields and place the form)
9. **Is “Require account approval” turned on for the form?** With approval on, applications wait in Customer Fields until you approve them.
   - Yes: go to fix N (Check pending customers in Customer Fields)
   - No: go to fix O (Applications go straight to Shopify)
10. **Does the form’s auto-tag rule add `b2b` to approved customers?** Check the rule on the form’s Rules tab.
   - Yes: go to fix I (Approval looks right: check the customer)
   - No / not sure: go to fix P (Add `b2b` in the auto-tag rule)
11. **Is the approval email set up in Customer Fields?** Approval emails for Customer Fields forms are sent by Customer Fields, not SparkLayer.
   - Yes: go to fix K (Check the email arrived)
   - No / not sure: go to fix Q (Set up the approval email in Customer Fields)
12. **Is there a link to the form page in your menu or footer?** Customers need a way to reach the page.
   - Yes: go to fix R (Everything checks out)
   - No: go to fix S (Link to the form from your store)

**Fixes**

- **A. Approve and Reject run on workflows** The buttons, the application status and new-entry emails are run by the form’s workflows, which are on the Growth plan and above. On lower plans the buttons show but do nothing. To approve by hand, create the customer in Shopify with the `b2b` tag and their group’s tag. See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
- **B. Shopify lets anyone create an account** With Shopify’s customer accounts, anyone can sign in with an emailed code. SparkLayer only appears for customers tagged `b2b`, so they see your store as retail. You can redirect them, show a banner pointing to your application form, or sign them out with a message. See [Wholesale-only stores](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md).
- **C. Check your form app’s settings** Make sure approved customers get the `b2b` tag and their group tag. That’s what gives them access to SparkLayer. Next: Wrong prices, payment methods or shipping for a customer?
- **D. Sign in with the code, using the right email** Customers sign in with a code sent to their email, with no password. If they use a different email from their customer record, Shopify creates a new retail customer without their tags. Where: Customers > select the customer > Tags (Shopify admin).
- **E. The customer needs to activate their account** With legacy accounts, a new customer must activate their account from the invite email before they can sign in. Open the customer, click More actions, then Send account invite. Where: Customers > select the customer > Tags (Shopify admin).
- **F. Check your customer accounts setting** Open Settings, then Customer accounts, to see which your store uses. Then start this check again. Where: Settings > Customer accounts (Shopify admin).
- **G. Add the form to a page** Add the form to a page on your live theme, such as a trade account page. Where: Forms (SparkLayer). See [Embed a form](https://docs.sparklayer.io/help/forms/embedding-and-styling.md).
- **H. Applications are arriving: add a notification** To be emailed about new applications, use a workflow with the Form submitted trigger and a Send email step. Workflows are on the Growth plan and above. On lower plans, check the Entries tab. Where: Forms (SparkLayer). See [Workflows](https://docs.sparklayer.io/help/forms/workflows.md).
- **I. Approval looks right: check the customer** If an approved customer still can’t see B2B pricing, check their tags and how they’re signing in. Next: SparkLayer not showing or looking wrong?
- **J. Check what approval does** Set the form’s approval to create the customer with the right customer group. Customers approved before the change need tagging by hand. Where: Forms (SparkLayer). See [Approve trade applications](https://docs.sparklayer.io/help/guides/approve-trade-applications.md).
- **K. Check the email arrived** Ask the customer to check their spam or junk folder, and check the email address on their application.
- **L. Add an email step to the approval workflow** Add a Send email step to the workflow that runs when you approve an application, so customers know they can sign in. Where: Forms (SparkLayer). See [Workflows](https://docs.sparklayer.io/help/forms/workflows.md).
- **M. Turn on Customer Fields and place the form** Enable Customer Fields in your theme editor, then add the form to your registration or wholesale page. Where: Online Store > Themes (Shopify admin).
- **N. Check pending customers in Customer Fields** With approval on, customers are only created in Shopify once you approve them. Review pending applications in the Customer Fields app.
- **O. Applications go straight to Shopify** With approval off, customers are created immediately. Check your Shopify customers list for new accounts. Where: Customers (Shopify admin).
- **P. Add `b2b` in the auto-tag rule** On the form’s Rules tab, make the auto-tag rule add `b2b`, and the group tag if you use one. Customers approved before the change need tagging by hand.
- **Q. Set up the approval email in Customer Fields** Turn on and edit the approved-customer email in the Customer Fields app.
- **R. Everything checks out** Your setup looks right, so we'll take it from here. Send us your answers with a link to the form page.
- **S. Link to the form from your store** Add a link to the form page in your header or footer menu so trade customers can find it.

- **Approve or Reject does nothing.** The buttons run workflows, which are on the Growth plan and above. Without them, [approve applications by hand](https://docs.sparklayer.io/help/forms/entries.md#approve-an-application-without-workflows).
- **No email arrives for new applications.** The notification email is a workflow too. Without workflows, check the form's entries yourself. Shopify Flow can't start from a SparkLayer form submission.
- **You can't find Forms in the Shopify app.** Forms are only in the SparkLayer Dashboard. See [You can't see Forms in the Shopify app](https://docs.sparklayer.io/help/troubleshooting.md#you-cant-see-forms-in-the-shopify-app).
- **Approving didn't create the customer.** Check what the workflow did on the entry. See [Check workflow runs](https://docs.sparklayer.io/help/forms/workflows.md#check-workflow-runs).
- **The applicant already has an account.** You'll see "That buyer already has an account". Move them to a group by changing their tags in Shopify. See [Invite a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md#invite-a-buyer).
- **Application emails don't arrive.** If you use Shopify's contact form, Shopify may not be delivering them. See [Send an email to the store owner](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md#send-an-email-to-the-store-owner).
- **You sell in several languages.** Make one form per language and add each one's embed code to the B2B login page's translations. See [Translate a form](https://docs.sparklayer.io/help/forms/embedding-and-styling.md#translate-a-form).

## Next steps

- [Keep wholesale hidden from retail shoppers](https://docs.sparklayer.io/help/guides/hide-wholesale-from-retail.md): Hide B2B products and prices from everyone else
- [Move your existing wholesale customers](https://docs.sparklayer.io/help/guides/move-existing-customers.md): Bring customers you already have onto SparkLayer
- [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md): Welcome emails, onboarding pages and going live


---

# Charge the right shipping on B2B orders

URL: https://docs.sparklayer.io/help/guides/b2b-shipping

Choose your store's shipping rates or SparkLayer's own, set B2B shipping methods and bands by order total or weight, pre-select a method and test the costs.

> **Quick summary**
>
> - You'll end up with B2B customers seeing the right shipping methods and costs at checkout, for their country, customer group and order.
> - Allow about 30 minutes, longer if you have many countries or weight bands.
> - SparkLayer shipping rates need the Starter plan or above. They work on every platform, with an extra step on Wix and BigCommerce.

By default, B2B customers see your store's own shipping methods at checkout, with nothing to set up. Use SparkLayer's own shipping rates when B2B customers need different rates from retail, or different rates for each customer group.

## Before you start

- **Your B2B shipping costs**, for example £20 under £99 and free above.
- **The countries you ship to**, and which customer groups get which methods.
- **Product weights**, if you charge by weight. Weight bands always use grams.

## Set up your shipping

### Step 1. Choose where your rates come from

| Use | When |
| --- | --- |
| **Your store's shipping methods** (the default) | B2B and retail pay the same, or your rates need complex rules or a shipping app. On Shopify, B2B-only methods need an app such as [Intuitive Shipping](https://docs.sparklayer.io/help/integrations/customer-experience/intuitive-shipping.md). |
| **SparkLayer shipping rates** | Different B2B rates for each customer group, by order total or weight, especially when retail and B2B share one store. |

B2B customers get one or the other, never both. To compare them, see [How it works](https://docs.sparklayer.io/help/ordering/shipping-rules.md#how-it-works) and [What SparkLayer shipping rules can do](https://docs.sparklayer.io/help/ordering/shipping-rules.md#what-sparklayer-shipping-rules-can-do).

If you keep your store's methods, skip to [step 5](#choose-which-method-is-pre-selected).

### Step 2. Turn on SparkLayer shipping rates

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 click **Save**. Wix and BigCommerce need an extra step. See [Turn on SparkLayer shipping rates](https://docs.sparklayer.io/help/ordering/shipping-rules.md#turn-on-sparklayer-shipping-rates).

### Step 3. Create a shipping method

Click **Create shipping method**, give it a name customers will understand, such as "Standard Shipping", and choose its countries and, if it's only for some groups, its customer groups. For every field, see [Create a shipping method](https://docs.sparklayer.io/help/ordering/shipping-rules.md#create-a-shipping-method).

### Step 4. Add shipping bands

A method only shows at checkout once it has a band. Add bands by order total or weight until every order is covered, with no gaps: the first band an order matches sets its cost. For the fields and an example (£20 under £99, free above), see [Add shipping bands](https://docs.sparklayer.io/help/ordering/shipping-rules.md#add-shipping-bands).

### Step 5. Choose which method is pre-selected

**Shopify only:**

SparkLayer pre-selects one of your Shopify shipping methods at checkout. Customers can pick another. To stop a free rate becoming the default, go to **Settings > Shipping > Automatic shipping selection** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping > Automatic shipping selection** in the Shopify app, choose **Prefer cheapest paid method** and click **Save**. See [Choose which method is pre-selected](https://docs.sparklayer.io/help/ordering/shipping-rules.md#automatic-shipping-selection).

**BigCommerce and Wix and WooCommerce and Magento only:**

**Automatic shipping selection** is for Shopify. With SparkLayer shipping rates, set each method's **Priority order** to choose the order customers see them in, with 1 first.

### Step 6. Test your shipping rates

Sign in as a B2B customer and go to **Review & Pay** with different countries, customer groups, order values and weights. Check the right methods and costs show. See [Test your shipping rates](https://docs.sparklayer.io/help/ordering/shipping-rules.md#test-your-shipping-rates).

**Shopify only:**

[Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order) opens your store as a test buyer, and test orders don't count towards your plan.

## Check it worked

- **Each test order shows the methods you expect** for its country and customer group.
- **Each cost matches the band** for its order total or weight, including the free band.
- **The pre-selected method** is the one you chose.

## If something's not right

- **No shipping methods show at checkout.** The customer doesn't match any method, or the order falls in a gap between bands. See [No shipping methods show at checkout](https://docs.sparklayer.io/help/troubleshooting.md#no-shipping-methods-show-at-checkout).
- **Free shipping isn't applied, or the wrong band wins.** The first band the order matches sets the cost, so check for overlapping ranges. See [Free shipping isn't applied, or the wrong rate shows](https://docs.sparklayer.io/help/ordering/shipping-rules.md#free-shipping-isnt-applied).
- **Free shipping is pre-selected when you'd rather it wasn't.** On Shopify, choose **Prefer cheapest paid method**. See [Choose which method is pre-selected](https://docs.sparklayer.io/help/ordering/shipping-rules.md#automatic-shipping-selection).
- **B2B customers see the same rates as retail.** That's how Shopify shipping works. Use a shipping app that sets rates by customer tag, or SparkLayer shipping rates. See [Show B2B-only shipping methods on Shopify](https://docs.sparklayer.io/help/ordering/shipping-rules.md#show-b2b-only-shipping-methods-on-shopify).
- **Shipping set up during a trial still shows after you change plan.** [Contact our support team](https://docs.sparklayer.io/help/support.md) to switch it off. See [If you set up shipping during a trial](https://docs.sparklayer.io/help/ordering/shipping-rules.md#if-you-set-up-shipping-during-a-trial).
- **Costs at checkout don't match your bands.** Check your products have valid weights and prices, then contact support. See [Shipping costs don't match the shipping bands](https://docs.sparklayer.io/help/ordering/shipping-rules.md#shipping-not-matching-the-shipping-bands).

## Next steps

- [Get B2B tax and VAT right](https://docs.sparklayer.io/help/guides/tax-and-vat.md): Make sure tax on products and shipping is right
- [Process your B2B orders in Shopify](https://docs.sparklayer.io/help/guides/process-orders-in-shopify.md): Change shipping on a draft order before you complete it
- [Shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md): Custom messages, local pickup and every setting


---

# Get B2B tax and VAT right

URL: https://docs.sparklayer.io/help/guides/tax-and-vat

Make sure B2B customers pay VAT or sales tax once: show net prices, allow for tax-inclusive store prices, exempt customers and check the tax at checkout.

> **Quick summary**
>
> - You'll end up with B2B prices shown without tax (net), VAT or sales tax added once at checkout, and tax-exempt customers paying none.
> - Allow about 20 minutes.
> - Tax handling is on every plan. SparkLayer doesn't calculate tax: it uses your platform's tax settings. Most of the settings here are in Shopify; other platforms have their own limits.

By default, SparkLayer shows B2B prices excluding tax, whatever your store's tax setting. On the **Review & Pay** step, it asks your platform for the tax and shows it as its own line. Tax goes wrong, for example VAT added twice, when the prices going in already include it.

## Before you start

- **Your tax rates**, for example 20% VAT, and whether any products are taxed differently.
- **Which customers are tax-exempt**, if any.
- **Whether you use a tax app**, such as Avalara or TaxJar.

## Set up tax

### Step 1. Check whether your store prices include tax

**Shopify only:**

In your Shopify admin, go to **Settings > Taxes and duties** ([open in the Shopify admin](https://admin.shopify.com/settings/taxes)). Under **Global settings**, see whether **Include sales tax in product price and shipping rate** is ticked. If it is, your Shopify prices include tax (gross).

**BigCommerce and Wix and WooCommerce and Magento only:**

Set tax up in your platform, then check its limits in [Set up tax on other platforms](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md#set-up-tax-on-other-platforms). For example, on Wix, tax exemptions only apply when the customer pays by card through the Wix checkout.

See [How it works](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md#how-it-works) for net and gross prices.

### Step 2. Make your price lists net

| Price list | What to do |
| --- | --- |
| **Manual** | Upload prices excluding tax (ex VAT). |
| **Automatic**, based on tax-inclusive Shopify prices | Work out a percentage that also takes the tax out, and enter it by hand. See [Tax-inclusive prices](https://docs.sparklayer.io/help/pricing/managing-pricing.md#tax-inclusive-prices) for how. |

Open the list 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, change it and click **Save**. [Take the 1-minute tour](https://docs.sparklayer.io/help/pricing/managing-pricing?tour).

### Step 3. Make tax-exempt customers exempt

**Shopify only:**

In your Shopify admin, open the customer, click **Manage tax exemptions**, untick **Collect tax** and click **Save**. If you use a tax app such as Avalara or TaxJar, exempt them there too (in Avalara, add them to the Exemption Customer List with their Shopify customer ID as the **Customer Code**): the two work independently. See [Make a customer tax-exempt](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md#make-a-customer-tax-exempt).

**BigCommerce and Wix and WooCommerce and Magento only:**

Set the exemption in your platform's customer settings. See [Set up tax on other platforms](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md#set-up-tax-on-other-platforms).

A tax-exempt customer still sees net prices, and pays no tax at checkout.

### Step 4. Handle products with different tax rates

**Shopify only:**

Optional. By default, tax is charged on the cart subtotal. If your products have different rates and Shopify's prices include tax, [contact our support team](https://docs.sparklayer.io/help/support.md) to turn on line item tax. To stop charging tax on a product, untick **Charge tax on this product** on it. See [Charge different tax rates on different products](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md#charge-different-tax-rates-on-different-products).

**BigCommerce and Wix and WooCommerce and Magento only:**

Set product tax rates in your platform's tax settings.

### Step 5. Show prices with tax, if your buyers expect it

Optional. Turn on **Tax-inclusive prices** at **Settings > Configurations > Pricing and cart** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Pricing and cart** in the Shopify app and add a `display_tax_rate` column to your price CSV, such as `10` for 10% GST. Buyers see gross prices labelled "inc. tax", but you still upload and charge net. It only works on manual price lists: see [Show tax-inclusive prices](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-tax-inclusive-prices). [Take the 1-minute tour](https://docs.sparklayer.io/help/dashboard/settings?tour).

## Sell to VAT-registered businesses in the EU

**Shopify only:**

A common setup for EU B2B sales: show net prices, add VAT at checkout, and zero-rate VAT-registered customers in other EU countries under the reverse charge.

1. **Show net B2B prices.** Upload prices excluding VAT to a manual price list, or adjust an automatic one. See [Make your price lists net](#make-your-price-lists-net).
2. **Collect VAT in each EU country you sell to.** In **Settings > Taxes and duties** ([open in the Shopify admin](https://admin.shopify.com/settings/taxes)), check the **Collecting tax** column for each country. VAT is then added on **Review & Pay**.
3. **Make reverse-charge customers tax-exempt.** For each VAT-registered EU customer who shouldn't pay VAT, open them in Shopify, click **Manage tax exemptions**, untick **Collect tax** and click **Save**. See [Make a customer tax-exempt](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md#make-a-customer-tax-exempt).
4. **Test it.** Place a test order as a VAT-registered customer and as one who pays VAT, and check the **Tax** line on each.

Shopify also charges VAT on shipping in the EU and the UK. See [Why is tax charged on shipping?](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md#why-is-tax-charged-on-shipping)

## Check it worked

Place a test order as a B2B customer, using a product whose price you know:

- **The product page and cart show the net price**, the same as the price list.
- **On Review & Pay**, **Tax** is its own line, at your rate, and the **Total** is the net price plus tax once.
- **As a tax-exempt customer**, **Tax** is zero.
- **On the order in your store**, the prices and tax match the checkout.

## If something's not right

These fixes are for Shopify. On other platforms, check your platform's tax settings and [its limits](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md#set-up-tax-on-other-platforms).

- **VAT or tax is charged twice.** Upload manual price lists excluding tax, and if your Shopify prices include tax, make sure each automatic price list's percentage also takes the tax out. See [Make your price lists net](#make-your-price-lists-net).
- **Tax shows as zero, or VAT is missing at checkout.** Check the customer isn't tax-exempt (**Manage tax exemptions** on the customer in Shopify, with **Collect tax** ticked), the product has **Charge tax on this product** ticked, and you collect tax in the country of their shipping address: in **Settings > Taxes and duties** ([open in the Shopify admin](https://admin.shopify.com/settings/taxes)), find the country and check its **Collecting tax** column. If those are right, check the customer record's default address, then place a test order as the customer.
- **An exempt customer is still charged.** A tax app such as Avalara or TaxJar overrides Shopify's settings, so exempt the customer in both. In Avalara, for example, add them to the Exemption Customer List with their Shopify customer ID as the **Customer Code**. See [Tax is charged but I use a third-party tax app](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md#tax-is-charged-but-i-use-a-third-party-tax-app-eg-avalara-taxjar).
- **Tax is charged on shipping.** In Canada, the EU, the UK and the US, Shopify taxes shipping whatever its settings say. See [Why is tax charged on shipping?](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md#why-is-tax-charged-on-shipping)
- **Order prices differ from the checkout.** The checkout uses whichever is lower, the SparkLayer price or the Shopify price, and that comparison includes tax: if the SparkLayer price after tax is higher than your tax-inclusive Shopify price, the Shopify price is used. Compare the variant's price at **Pricing > Price editor** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/editor)), or **SparkLayer Wholesale > Pricing > Price editor** in the Shopify app with its **Price** in Shopify. See [Prices on the Shopify order don't match the SparkLayer checkout](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md#prices-on-the-shopify-order-dont-match-the-sparklayer-checkout).

For every tax question, see [Troubleshooting](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md#troubleshooting) in Tax and shipping.

## Next steps

- [Set up wholesale prices](https://docs.sparklayer.io/help/guides/set-up-wholesale-prices.md): Create price lists and assign them to customer groups
- [Charge the right B2B shipping](https://docs.sparklayer.io/help/guides/b2b-shipping.md): Set B2B shipping methods and costs
- [How tax works at checkout](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md): Every tax setting, by platform


---

# Fix customers or products that won't sync

URL: https://docs.sparklayer.io/help/guides/fix-sync-problems

Find products and B2B customers that haven't reached SparkLayer, fix missing SKUs, incomplete addresses and tag errors in your store, then check they sync.

> **Quick summary**
>
> - You'll end up with every product and B2B customer synced to SparkLayer, so buyers see their prices when they sign in.
> - Allow about 15 minutes, plus the time to fix the records in your store.
> - Sync is on every plan and platform. Product sync is at **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app, and customer sync errors show as a banner at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app.

SparkLayer keeps a copy of your products, and of customers tagged `b2b`, from your store. A product or customer that doesn't sync can't get B2B prices. The fix is almost always in your store: a missing SKU, a draft product or an incomplete address. See [How sync works](https://docs.sparklayer.io/help/integrations/data-sync.md#how-sync-works).

## Before you start

- **The product's SKU, or the customer's email**, for anything you know is missing.
- **Access to edit products and customers** in your store admin.

## Fix products

### Step 1. Check product sync

Go to **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app. When everything is working, the banner reads **Products are up to date**. See [Check your products are syncing](https://docs.sparklayer.io/help/integrations/data-sync.md#check-your-products-are-syncing).

### Step 2. Look up the missing product

In **Product data lookup**, search by name, SKU, barcode or ID. If it says **No products found**, SparkLayer doesn't have it. See [Look up a product's data](https://docs.sparklayer.io/help/integrations/data-sync.md#look-up-a-products-data).

If the banner shows errors instead of **Products are up to date**, the rest of your products still sync, but fix the errors:

| Error message | Fix |
| --- | --- |
| **Check SKUs are assigned to all variants in Shopify** | The product, or one of its variants, has no SKU. Add one in the product's **Inventory** section. SparkLayer only imports products with a SKU on every variant. |
| **Please ensure the variant slug is unique** or **Please ensure the variant SKU is unique** | Search your store for the SKU and rename any duplicate. If you recently deleted the product and added it again, an old copy may still be in SparkLayer: [contact support](https://docs.sparklayer.io/help/support.md) and we'll remove it. |
| **Metafield(s) configurations appear to be invalid (rrp)** | The variant's `rrp` field must hold a price and currency, such as `[{"value":15.99,"currency_code":"usd"}]`, not just a number. See [Show RRP](https://docs.sparklayer.io/help/guides/show-rrp.md). |

### Step 3. Fix the product in your store

**Shopify only:**

In your Shopify admin, check the product:

- Has a unique SKU on every variant, in the **Inventory** section
- Is **Active**, not **Draft**
- Is included in the **SparkLayer Wholesale** sales channel

See "Do my products need SKUs?" in [Shopify FAQs](https://docs.sparklayer.io/help/platforms/shopify/faqs.md#products).

**BigCommerce and Wix and WooCommerce and Magento only:**

In your platform's admin, check the product has a unique SKU on every variant and is active. See your platform's guide in [Platforms](https://docs.sparklayer.io/help/platforms.md).

Then wait for the next partial sync. SparkLayer refreshes products every 10 minutes, so the fixed product syncs then.

## Fix customers

### Step 1. Check customer sync

Go to **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app. If some customers didn't sync, a banner such as **Customers sync completed with 3 errors** shows at the top. Click **Show errors** to see each customer and the problem. See [Fix customer sync errors](https://docs.sparklayer.io/help/integrations/data-sync.md#fix-customer-sync-errors). [Take the 1-minute tour](https://docs.sparklayer.io/help/customers/managing-customers?tour).

### Step 2. Fix each customer in your store

**Shopify only:**

Click **Open customers in Shopify** and fix each record:

| Error message | Fix |
| --- | --- |
| **Missing a default shipping address** | Add a default shipping address, with a country, first line, city and postcode or ZIP code. |
| **Address - The Country assigned is incomplete or invalid**, **Address - The City is missing and is a required field**, **Address - The address needs a first line added (Line 1)** or **Address - the Post/Zip code is invalid and is a required field** | Add the missing country, city, first line or postcode or ZIP code. This applies to every address in the customer's address book, including second and older addresses: an incomplete second address causes an error even when the default is complete. Complete it or delete it. |
| **Tagged b2b-trade but no first or last name**, or the same message with another group tag | Add the customer's first and last name. |
| **Invalid customer group**, such as `{"code":"resource-id-not-found","message":"Invalid customer group "tier-1"."}` | The customer has a tag, such as `b2b-tier-1`, that doesn't match any group at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app, for example because the group was deleted. Fix the tag, or create the group. |
| Address doesn't sync, with no error | Check the address for unusual characters, such as a long dash (―), in the first line, and replace them with plain text. |
| Not in the list at all | Add the `b2b` tag. Only customers tagged `b2b` sync. |

If a customer still won't sync, check whether their email address changed recently. It shouldn't cause problems, but it sometimes affects syncing.

**Customers with a sales agent groups metafield**

Older setups used a **sales agent groups** metafield (`sparklayer.sales_agent_groups`) on each customer. If customers with it don't sync, check the metafield's definition in **Settings > Custom data** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data)) is set to **Limit to preset choices**. See [Set up the sales agent groups metafield](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#set-up-the-sales-agent-groups-metafield).

**BigCommerce and Wix and WooCommerce and Magento only:**

Fix each customer in your platform's admin. Check they're marked as B2B for your platform and have a complete address. On Wix, they must also be a **Site Member**. See [Assign customers to a customer group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group).

### Step 3. Wait for the next sync

Fixed customers sync on the next partial sync. You don't need to start it yourself. If a customer still hasn't synced after you've fixed them, [contact support](https://docs.sparklayer.io/help/support.md).

## Check it worked

- **The product sync banner** shows **Products are up to date**, and **Product data lookup** finds the product.
- **The customer appears at** **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app, with the right customer group in the **Group** column.
- **The customer signs in** and sees B2B prices on the product.

## If something's not right

- **Product data lookup says "No products found".** See [Product data lookup says "No products found"](https://docs.sparklayer.io/help/troubleshooting.md#the-product-data-sync-says-this-product-cannot-be-found).
- **A customer isn't in the Customers list.** See [A customer isn't in the Customers list](https://docs.sparklayer.io/help/troubleshooting.md#the-customer-data-sync-says-this-customer-id-cannot-be-found).
- **You can't choose a pricing source for an automatic price list.** SparkLayer can't find SKUs on your store. See [You can't choose a source for an automatic price list](https://docs.sparklayer.io/help/troubleshooting.md#you-cant-choose-a-source-for-an-automatic-price-list).
- **The customer synced but sees no B2B prices.** See [Customers can't see B2B prices](https://docs.sparklayer.io/help/troubleshooting.md#customers-cant-see-b2b-prices-or-products-say-unavailable).

## Next steps

- [Move your existing wholesale customers](https://docs.sparklayer.io/help/guides/move-existing-customers.md): Tag customers in bulk and import their order history
- [Set up wholesale prices](https://docs.sparklayer.io/help/guides/set-up-wholesale-prices.md): Give synced products their B2B prices
- [Troubleshooting](https://docs.sparklayer.io/help/troubleshooting.md): Every symptom, with the checks to fix it


---

# Move your existing wholesale customers onto SparkLayer

URL: https://docs.sparklayer.io/help/guides/move-existing-customers
Applies to: Shopify

Bring the trade customers already in your Shopify store onto SparkLayer: tag them into groups, import their terms and order history, then ask them to sign in.

> **Quick summary**
>
> - You'll end up with your existing trade customers in the right customer groups, with their payment terms and past orders, ready to sign in and order.
> - Allow an hour or two, depending on how many customers you have. A bulk import app saves time for large lists.
> - Customer groups and customer-specific pricing are on every plan. Everything in this guide is for Shopify.

Customers already in Shopify become B2B customers through their tags, so there's nothing to recreate. You tag them, bring across anything stored on them, and tell them they can sign in.

## Before you start

- **Your price lists and customer groups set up.** See [Set up wholesale prices](https://docs.sparklayer.io/help/guides/set-up-wholesale-prices.md).
- **A list of your trade customers** and the group each belongs in.
- **Their credit limits and terms**, if they pay on account.
- **Your previous wholesale app still installed**, if you have one. SparkLayer can run alongside it while you test.

## Move your customers

### Step 1. Tag your trade customers

In your Shopify admin, give each trade customer the `b2b` tag, plus their group's tag if it isn't the Base group, for example `b2b-trade`. You'll find each group's tag under its name at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app.

Use no more than 2 B2B tags per customer, and check each has at least one complete address. See [Tag existing customers in Shopify](https://docs.sparklayer.io/help/platforms/shopify/install.md#tag-your-customers-in-shopify). [Take the 1-minute tour](https://docs.sparklayer.io/help/customers/customer-groups?tour).

**More detail**

Don't use **Invite a buyer** for customers who already have an account: you'll see "That buyer already has an account". It's for new buyers.

### Step 2. Bring across their terms and prices

If customers have credit limits, net terms or their own price lists, these go in [metafields](https://docs.sparklayer.io/help/platforms/shopify/metafields.md) on each customer. To fill them in for many customers at once, use Shopify's bulk editor, or an import app such as Matrixify if the values are already in a spreadsheet. See [Fill in metafields for many at once](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#import-metafields-in-bulk).

For the values to enter, see [Credit limits and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md#what-to-enter) and [Prices for one customer](https://docs.sparklayer.io/help/pricing/customer-pricing.md).

### Step 3. Check they've synced

Go to **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app and check each customer is there, with the right group in the **Group** column. If a sync banner shows errors, click **Show errors** and fix those customers in Shopify. See [Check a customer has synced](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#check-a-customer-has-synced). [Take the 1-minute tour](https://docs.sparklayer.io/help/customers/managing-customers?tour).

### Step 4. Import their order history

So customers see their previous orders in My Account, add an order metafield with the namespace `sparklayer`, key `order_import` and type `boolean`. Set it to `true` on each order you want to import, and check each order has the `b2b` tag.

Do this after SparkLayer is installed. For many orders, use Matrixify with our sample CSV template. See [Import order history into SparkLayer](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#import-order-history-into-sparklayer).

### Step 5. Tell your customers they can sign in

Customers sign in at your store's login page, for example `www.yourstore.com/account`. If you use Legacy customer accounts, send each one Shopify's account invite first. Email them to say your B2B store is ready, starting with a small group. See [Invite your first customers](https://docs.sparklayer.io/help/get-started/launching.md#invite-your-first-customers) and our [example welcome email](https://docs.sparklayer.io/help/get-started/launching.md#send-a-welcome-email).

**More detail**

To invite many customers at once, apps such as Matrixify and BAIS Bulk Account Invite can help. See [Invite customers in bulk](https://docs.sparklayer.io/help/get-started/launching.md#invite-customers-in-bulk).

### Step 6. Retire your old wholesale app

Once you're happy with SparkLayer, uninstall your previous B2B app. If it changed your theme code, you can ask its developer to remove the changes, but you don't have to. See "What if I already use a wholesale app on my store?" in [Shopify FAQs](https://docs.sparklayer.io/help/platforms/shopify/faqs.md#theme-and-storefront).

**Old SparkLayer scripts**

SparkLayer now adds a **B2B Ordering** app pixel to **Settings > Customer events** ([open in the Shopify admin](https://admin.shopify.com/settings/customer_events)) when you install it. If an older SparkLayer install added scripts to your checkout or thank-you page, you can delete them once the pixel shows as connected: see [Can I delete old SparkLayer scripts from Additional Scripts?](https://docs.sparklayer.io/help/platforms/shopify/faqs.md#can-i-delete-old-sparklayer-scripts-from-additional-scripts)

## Check it worked

- **Every customer is at** **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app, in the right group.
- **Signed in as one of them,** you see their trade prices.
- **In My Account,** their imported orders show in their order history, and **Financials** shows any credit limit and terms.

## If something's not right

- **Customer sync shows errors.** Usually an incomplete address or a tag that doesn't match a group. See [Customer sync shows errors](https://docs.sparklayer.io/help/troubleshooting.md#the-customer-data-sync-shows-errors).
- **A customer isn't in the Customers list.** See [A customer isn't in the Customers list](https://docs.sparklayer.io/help/troubleshooting.md#the-customer-data-sync-says-this-customer-id-cannot-be-found).
- **SparkLayer doesn't appear when they sign in.** Check their tags and address, and that you're testing on the right theme. See [Widgets don't appear when a B2B customer signs in](https://docs.sparklayer.io/help/troubleshooting.md#widgets-dont-appear-when-a-b2b-customer-signs-in).
- **Their old orders don't show.** Check each order has the metafield set to `true` and the `b2b` tag. See [Import order history into SparkLayer](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#import-order-history-into-sparklayer).

## Next steps

- [Fix customers or products that won't sync](https://docs.sparklayer.io/help/guides/fix-sync-problems.md): Find and fix sync errors
- [Let trusted customers pay later on Net 30](https://docs.sparklayer.io/help/guides/net-terms.md): Set credit limits and payment terms
- [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md): Onboarding pages, welcome emails and going live


---

# Run volume pricing and promotions for trade customers

URL: https://docs.sparklayer.io/help/guides/volume-discounts

Reward bigger B2B orders with quantity price breaks and pack sizes, then run discounts such as volume tiers and coupon codes for chosen customer groups.

> **Quick summary**
>
> - You'll end up with lower unit prices for larger quantities, products sold in packs if you need them, and promotions such as "5% off 24 or more units" for the customer groups you choose.
> - Allow about 30 minutes, plus time to prepare a CSV of price breaks.
> - Quantity pricing and pack sizes are on every plan. Pack sizes aren't available on Wix. [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md) need the Growth plan or above, including the 14-day Growth trial.

There are 3 ways to reward bigger orders, and you can combine them. Quantity pricing changes a product's price as the quantity goes up. Pack sizes control how many customers can order. Discounts sit on top of your price lists, so you can run a promotion without changing anyone's prices.

## Before you start

- **Your price lists set up.** See [Set up wholesale prices](https://docs.sparklayer.io/help/guides/set-up-wholesale-prices.md).
- **Your price breaks**, for example 14.99 each from 1 unit and 10.99 each from 5.
- **The customer groups** a promotion is for, and any coupon code or dates.

## Set it up

### Step 1. Choose the right tool

| To | Use |
| --- | --- |
| Lower a product's unit price as the quantity goes up | [Quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md) (step 2) |
| Sell a product in packs, or set a minimum quantity | [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md) (step 3) |
| Run a promotion, such as more off as the quantity goes up, money off over a spend, or a coupon code | [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md) (steps 4 to 6) |

### Step 2. Add quantity price breaks

Prepare a CSV file with `sku`, `price` and `qty` columns, one row per price break. Always include a row for a quantity of `1`:

```csv
sku,price,qty
123-abc,14.99,1
123-abc,10.99,5
```

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, click **Upload** next to the price list, check the rows and click **Import**. Quantity pricing works with prices you upload, not with an automatic pricing rule. See [Set up quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md#set-up-quantity-pricing).

To change the breaks for one product, use the [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md). [Take the 1-minute tour](https://docs.sparklayer.io/help/pricing/price-editor?tour).

### Step 3. Set pack sizes or minimum quantities

Optional. Pack sizes and minimums are set in a metafield on each product variant.

**Shopify only:**

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. In the **Metafields** card, click **Configure** next to **SparkLayer metafields** to add **B2B - Pack Size** to your variants. Then open the product in your Shopify admin, select a variant, enter the pack size, for example `6`, and click **Save**.

**Lots of products? Fill them in one table (Shopify):** in your Shopify admin, go to **Products**, tick the products and click **Edit products**. Click **Columns**, tick **B2B - Pack Size** under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

**BigCommerce and WooCommerce and Magento only:**

Add a variant-level `sparklayer` field with the key `pack_size`, as your platform's metafields guide describes, and enter the pack size on each variant.

**Wix only:**

Wix doesn't support metafields, so pack sizes and product quantity limits aren't available.

See [Set a pack size](https://docs.sparklayer.io/help/storefront/quantity-rules.md#product-pack-sizing) and [Set minimum and maximum quantities](https://docs.sparklayer.io/help/storefront/quantity-rules.md#set-minimum-and-maximum-quantities).

### Step 4. Create a discount

Go to **Pricing > Discounts** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/discounts)), or **SparkLayer Wholesale > Pricing > Discounts** in the Shopify app and click **Create discount**. Enter a **Discount internal name**, a **Discount handle (or ID)** and a **Discount public name**, which customers see. See [Create a discount](https://docs.sparklayer.io/help/pricing/discounts.md#create-a-discount). [Take the 1-minute tour](https://docs.sparklayer.io/help/pricing/discounts?tour).

For more off as the quantity goes up, choose **Advanced requirements and rewards** under **Type**. Set each tier's **Minimum units** and **Discount**, and click **Add tier** for more. See [Set up volume tiers](https://docs.sparklayer.io/help/pricing/discounts.md#set-up-volume-tiers).

### Step 5. Choose which products it applies to

Optional. Under **Rules**, click **New rule** to add the products, collections or tags the cart must include before the discount applies. See [Restrict a discount to certain products](https://docs.sparklayer.io/help/pricing/discounts.md#restrict-a-discount-to-certain-products).

### Step 6. Choose who gets it, and when

Under **Requirements**, tick **Customer groups** and choose the groups. Add a **Coupon codes** requirement if customers should enter a code, and **Scheduling** for start and end dates. Click **Save**. See [Limit a discount to customer groups](https://docs.sparklayer.io/help/pricing/discounts.md#limit-a-discount-to-customer-groups) and [Limit who can use a discount and when](https://docs.sparklayer.io/help/pricing/discounts.md#limit-who-can-use-a-discount-and-when).

## Check it worked

Signed in as a customer in the group:

- **The product page shows the price breaks**, as a table of **Qty**, **Price** and **Savings**.
- **The quantity selector moves in packs**, if you set a pack size.
- **The cart shows the discount** once the order meets its requirements, or once you enter the coupon code.
- **A customer in another group** doesn't get the discount.

## If something's not right

- **Price breaks don't show.** Check the `qty` column and that every SKU has a price for a quantity of 1. See [Tiered pricing doesn't show](https://docs.sparklayer.io/help/troubleshooting.md#tiered-pricing-doesnt-show).
- **A discount isn't applied.** Check it's **Active** and the order meets every requirement. See [Why wasn't a discount applied to an order?](https://docs.sparklayer.io/help/pricing/discounts.md#why-wasnt-a-discount-applied-to-an-order)
- **There's no coupon box at checkout.** It only shows when an active discount uses a coupon code. See [I don't see the discount coupon box](https://docs.sparklayer.io/help/pricing/discounts.md#i-dont-see-the-discount-coupon-box-on-the-checkout).
- **You can't save a discount.** On Basic or Starter, discounts need Growth. See [Why can't I save a discount?](https://docs.sparklayer.io/help/pricing/discounts.md#why-cant-i-save-a-discount)

## Next steps

- [Give a key account their own prices](https://docs.sparklayer.io/help/guides/key-account-prices.md): Set different prices for one company or customer
- [Charge the right B2B shipping](https://docs.sparklayer.io/help/guides/b2b-shipping.md): Offer free shipping over a spend
- [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md): Every discount type and requirement


---

# Show RRPs to your trade customers

URL: https://docs.sparklayer.io/help/guides/show-rrp
Applies to: Shopify, BigCommerce, WooCommerce, Magento

Show each product's RRP (MSRP) beside the B2B price: copy your Shopify prices with a ready-made Flow, or fill in your whole catalogue from a spreadsheet.

> **Quick summary**
>
> - You'll end up with every product showing its RRP (also called MSRP) next to the customer's B2B price, for example "£6.75" with "RRP: £29.99", so trade customers see their margin.
> - The RRP lives in a field on each product variant, called `rrp`. SparkLayer adds the field for you; this guide is about filling it in without typing it product by product.
> - If your RRP is your Shopify price, a Shopify Flow fills it in for you. If it's a different price, or you sell in several currencies, fill it in from a spreadsheet. Allow about 20 minutes either way.
> - Works on Shopify, BigCommerce, WooCommerce and Magento. Wix doesn't support metafields, so RRPs aren't available on Wix.

Each variant's `rrp` field holds its retail price and the currency, written like this: `[{"value":29.99,"currency_code":"usd"}]`. The value is a decimal amount, such as `29.99`, not a number of cents or pence. You never have to type that by hand: every route below writes it for you.

## Choose your route

| Your RRP is | Use | How it stays up to date |
| --- | --- | --- |
| The same as your Shopify price | [Shopify Flow](#copy-your-shopify-prices-with-shopify-flow) | Automatically, every hour |
| A different price, or in several currencies | [A spreadsheet](#fill-in-rrps-from-a-spreadsheet) | Import again when your RRPs change |
| Only needed on a few products | [By hand](#fill-in-a-few-products-by-hand) | Edit the product |

Using Shopify Flow? It fills in products as they change, so do a one-off [spreadsheet import](#fill-in-rrps-from-a-spreadsheet) first to cover the products you already have.

## Before you start

- **The RRP field.** On Shopify, go to **Integrations > Platform > Metafields** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Metafields** in the Shopify app, click **Configure** next to **SparkLayer metafields** and enable the RRP field. On other platforms, your developer adds a variant-level `sparklayer.rrp` field of the type JSON: see [Metafields](https://docs.sparklayer.io/developers/data/metafields.md).
- **Your currency code**, in lowercase: the 3 letters for the currency your B2B prices are in, such as `usd`, `gbp` or `eur`.

## Copy your Shopify prices with Shopify Flow

**Shopify only:**

### Step 1. Install Shopify Flow

[Shopify Flow](https://apps.shopify.com/flow) is a free Shopify app, available on every Shopify plan. Install it from the Shopify App Store.

### Step 2. Import our RRP workflow

1. Download our workflow: [Update RRP metafield when a product is updated](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/Update_RRP_Metafield_when_product_updated.flow?v=1772815525).
2. In your Shopify admin, go to **Apps** > **Flow** and click **Import**.
3. Click **Add files**, choose the file you downloaded and click **Import**.

### Step 3. Set your currency and timing

The workflow opens in Flow's editor. Before you turn it on, change two settings:

1. Click the **Get product variant data** step. In its **Query**, change `15 minute` to `60 minute`. The workflow runs once an hour, so this makes it pick up every change since its last run.
2. Click the **Update product variant metafield** step. In its **Value**, change `gbp` to your currency code, for example `usd`.
3. Click **Turn on workflow**.

**What the workflow does**

Once an hour, it finds the variants that changed in the last hour, up to 100 of them, and writes each one's Shopify price into its `rrp` field. New products are included, because adding a product counts as a change. 100 is the most Flow's **Get product variant data** step can return in one run.

### Step 4. Fill in the products you already have

The workflow only picks up products as they change. Fill in your existing catalogue once with a [spreadsheet import](#fill-in-rrps-from-a-spreadsheet), using your **Variant Price** column as the RRP.

**BigCommerce and WooCommerce and Magento only:**

Shopify Flow is only on Shopify. On BigCommerce, WooCommerce and Magento, fill in your RRPs [from a spreadsheet](#fill-in-rrps-from-a-spreadsheet).

## Fill in RRPs from a spreadsheet

A spreadsheet fills in every variant in one import, whatever your RRPs are. On Shopify, use the [Matrixify](https://apps.shopify.com/excel-export-import) app to export and import. On other platforms, use your platform's product export and import, or ask your developer.

### Step 1. Export your products

Export your products, including their variants, as an Excel or CSV file. Each variant has its own row, with its price. In Matrixify, export **Products**: the price is in the **Variant Price** column.

### Step 2. Add the RRP column

Open the file in Excel or Google Sheets and add a column for the RRP field. For Matrixify, head it `Variant Metafield: sparklayer.rrp [json]`.

Then fill in the form with the column that holds each variant's RRP: **Variant Price** if your RRP is your Shopify price, or a column you've added with your RRPs. It writes a formula that turns each price into the right format. Paste it into the first row of your new column, then fill it down to the last row.

Rows with no price stay empty, so those variants won't show an RRP. If your spreadsheet writes decimals with a comma, such as `29,99`, set its language to English for this file first, so prices come out as `29.99`.

### Step 3. Import the file

So nothing else changes, delete every column except the IDs and your RRP column. For Matrixify, keep **ID** and **Variant ID**: Matrixify uses them to find and update each variant. Then import the file.

## Fill in a few products by hand

For one or two products, enter the RRP and its currency in the form. It writes the value for you. Click **Copy**, open the variant in your store admin, paste the value into its `rrp` field and save.

**Lots of products? Fill them in one table (Shopify):** in your Shopify admin, go to **Products**, tick the products and click **Edit products**. Click **Columns**, tick the SparkLayer field under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

## Choose how RRPs and savings show

Optional. At **Storefront > Options > Pricing and display** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Pricing and display** in the Shopify app, you can turn on **Base savings on RRP**, so savings are worked out from the RRP, and **RRP toggle**, so buyers can switch between the RRP and their own prices. Click **Save and publish**. See [How prices are shown](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-an-rrp-msrp-price).

## Check it worked

Signed in as a B2B customer, or with [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order):

- **The product page shows the RRP** under the price, for example "RRP: £29.99", on each variant.
- **In your store admin**, a variant's `rrp` field holds a value such as `[{"value":29.99,"currency_code":"gbp"}]`, with your currency.
- **On Shopify Flow**, the workflow's **Runs** show it running each hour without errors.

## If something's not right

- **No RRP shows.** Check the value is on the variant, not the product, and that you're signed in as a B2B customer. The RRP's currency must match the currency of the customer's prices.
- **Only some products show an RRP.** With Shopify Flow, products that haven't changed since you turned it on have no RRP yet. Fill them in with a [spreadsheet import](#fill-in-rrps-from-a-spreadsheet).
- **The product shows the same RRP for every variant.** On a product with several variants, the RRP in the product summary is the first variant's, in your platform's variant order, and it doesn't change when the customer picks another variant. A range isn't available yet. Each variant's own RRP shows in the variant table. See [Show an RRP (MSRP) price](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-an-rrp-msrp-price).
- **The RRP shows in the wrong currency.** The workflow still has `gbp` in its value. Change it to your currency code, as in [Set your currency and timing](#set-your-currency-and-timing).
- **A price changed but the RRP didn't.** The workflow updates up to 100 variants an hour. After a big price change, import your RRPs again from a spreadsheet. Check the workflow's **Runs** in Shopify Flow for errors.
- **You're on Wix.** Wix doesn't support metafields, so RRPs aren't available.

## Next steps

- [How prices are shown](https://docs.sparklayer.io/help/pricing/pricing-display.md): Every way to change how prices show, including RRP-only mode
- [Shopify Flow for B2B](https://docs.sparklayer.io/help/platforms/shopify/customisations/flow.md): More ready-made workflows for orders, customers and products
- [Set up wholesale prices](https://docs.sparklayer.io/help/guides/set-up-wholesale-prices.md): Give trade customers their prices


---

# Pricing

URL: https://docs.sparklayer.io/help/pricing

How B2B pricing works in SparkLayer: price lists, the three ways to fill them, how customer groups decide who sees which prices, and where to set each up.

> **Quick summary**
>
> - B2B prices live in **price lists**: a set of prices for your products, matched by SKU, in one currency. Manage them 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.
> - A price list gets its prices **automatically** from your store's prices (for example 50% off retail), **manually** by CSV upload or the Price editor, or from another system such as an ERP through an **integration**.
> - Customers see a price list's prices when they sign in, once it's assigned to their **customer group**, their company or them individually.
> - The free Basic plan includes up to 3 price lists; Starter and above have unlimited price lists. [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md) need the Growth plan. See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).

Pricing builds up in layers. You start with a price list, choose who sees it, then add quantity pricing and discounts where you need them. This page explains each layer in that order, and how they combine into the price a customer pays.

## How pricing works

A [price list](https://docs.sparklayer.io/help/glossary.md#price-list) holds your B2B prices. Each price is set against a product SKU (at variant level), so every product you sell to B2B customers needs a unique SKU.

You assign price lists to [customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md), and every B2B customer belongs to a group. When customers sign in, the SparkLayer widgets on your store show them the prices from their group's price lists.

How a price reaches a B2B customer:

1. **Prices go in**: Automatic, CSV upload or an integration
2. **Price list**: Prices per SKU, in one currency
3. **Customer group**: Each group is assigned one or more price lists
4. **Customer signs in**: They see their group's prices on your store

Prices are always shown to B2B customers **net** (excluding tax). Tax is added at checkout, depending on how tax is set up in your store. If your buyers expect to see prices with tax included, see [tax-inclusive price display](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-tax-inclusive-prices). If your store's own prices include tax, see [If your store's prices include tax](https://docs.sparklayer.io/help/pricing/managing-pricing.md#tax-inclusive-prices) before you set up automatic pricing.

## Automatic, manual or integration

Prices get into a price list in 3 ways. Choose the one that matches where your trade prices come from today.

| Way | What it means | Example | Set it up |
| --- | --- | --- | --- |
| **Automatic** | SparkLayer works out prices from a pricing source, such as your store's own prices, with a percentage increase or decrease. Prices update when your store's prices change. | 50% off your store's retail prices | [Set up automatic pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md#set-up-automatic-pricing) |
| **Manual** | You set exact prices per SKU by uploading a CSV file, or edit single prices in the Price editor. | A CSV of specific trade prices | [Upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md) |
| **Integration** | A backend system such as an ERP, PIM or CRM sends prices to SparkLayer through the API. Available on the Pro and Enterprise plans. | Sync prices from NetSuite | [Send prices from another system](https://docs.sparklayer.io/help/pricing/managing-pricing.md#send-prices-from-another-system) |

You can combine them. For example, an automatic price list at 50% off retail can also hold exact prices for a few products, set by CSV upload or with **Override for this SKU** in the [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md).

## Who sees which prices

Customer groups set the prices for most customers. When one business or person needs something different, you can go a level further:

| Level | Set it at | Guide |
| --- | --- | --- |
| **Customer group** | **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app. One or more price lists per group. | [Assign a price list to customers](https://docs.sparklayer.io/help/pricing/managing-pricing.md#assign-a-price-list-to-customers) |
| **Company or location** | The company or location page, under **Prices and rules**. | [Give a company its own price list](https://docs.sparklayer.io/help/pricing/customer-pricing.md#give-a-company-its-own-price-list) |
| **One customer** | Their own price lists, or an extra percentage discount, on their record in your store. | [Prices for one customer](https://docs.sparklayer.io/help/pricing/customer-pricing.md) |

To give one key account their own prices, step by step, follow [Give a key account their own prices](https://docs.sparklayer.io/help/guides/key-account-prices.md).

## Quantity pricing and discounts

Once customers have the right price list, 2 features can lower what they pay:

- **[Quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md)** lowers the unit price as the quantity rises, for example buy 1 at $10 or 10 at $8. You set it in a price list. Quantities can be counted per variant or across the parent product.
- **[Discounts](https://docs.sparklayer.io/help/pricing/discounts.md)** add promotions on top of price lists: order discounts, volume tiers and coupon codes. They need the Growth plan.

To set up both for bigger orders, follow [Run volume pricing and promotions for trade customers](https://docs.sparklayer.io/help/guides/volume-discounts.md).

## How it all fits together

SparkLayer works out a customer's price in this order:

| Step | What happens | Guide |
| --- | --- | --- |
| 1. Price list | The most specific price list applies: the customer's own price lists, then their company location's, then their company's, then their customer group's. If a product is in several of the group's lists, the first one wins. | [What overrides what](https://docs.sparklayer.io/help/customers.md#who-sets-what) and [Which price list wins](https://docs.sparklayer.io/help/pricing/managing-pricing.md#price-list-order) |
| 2. Quantity price | If the price list has price breaks, the unit price comes from the break the quantity falls into. | [Quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md) |
| 3. Customer discount | A customer's extra percentage discount, if set, is taken off the unit price. | [Prices for one customer](https://docs.sparklayer.io/help/pricing/customer-pricing.md#give-a-customer-an-extra-percentage-discount) |
| 4. Discounts | Any discounts the cart qualifies for apply on top, for example an amount off the order's sub-total. | [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md) |
| 5. Tax | Tax is added at checkout. | [Tax and shipping](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md) |

## Set up B2B pricing for the first time

B2B pricing takes 4 steps to set up, and needs no code.

1. Check that every product you sell to B2B customers has a **unique SKU** in your store. SparkLayer matches prices to products by SKU.
2. Create a price list 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. See [Create a price list](https://docs.sparklayer.io/help/pricing/managing-pricing.md#create-a-price-list).
3. Fill it with prices: a percentage off your store's prices ([automatic pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md#set-up-automatic-pricing)), or exact prices from a spreadsheet ([upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md)).
4. Assign the price list to a customer group at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app. To give every B2B customer the same prices, assign it to the **Base customer group**. See [Assign a price list to customers](https://docs.sparklayer.io/help/pricing/managing-pricing.md#assign-a-price-list-to-customers).

Then sign in to your store as a test B2B customer to check the prices. See [Test as a B2B customer](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#test-as-a-b2b-customer). For the same setup as one guide, from price list to first buyer, follow [Set up wholesale prices for your trade customers](https://docs.sparklayer.io/help/guides/set-up-wholesale-prices.md).

## Supported pricing rules

Everything SparkLayer's pricing engine supports, and where to set it up:

| Rule | What you can do | Guide |
| --- | --- | --- |
| **Currencies** | Set up price lists in different currencies. | [Price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md) |
| **Customer rules** | Assign one or more price lists to a customer group, a company or a single customer, and give individual customers an extra percentage discount. | [Prices for one customer](https://docs.sparklayer.io/help/pricing/customer-pricing.md) |
| **Quantity pricing** | Lower the unit price as the quantity rises. Count quantities per variant or across the parent product. | [Quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md) |
| **Discounts and promotions** | Add order discounts, volume tiers and coupon codes on top of price lists. Needs the Growth plan. | [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md) |
| **Pricing display** | Show RRP (MSRP), quantity price breaks, unit costs and tax-inclusive prices. | [How prices are shown](https://docs.sparklayer.io/help/pricing/pricing-display.md) |
| **Quantity rules** | Set minimum and maximum order quantities and pack sizes per customer group. | [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md) and [storefront features](https://docs.sparklayer.io/help/storefront.md) |

## Pricing guides

- [Price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md): Create automatic and manual price lists and assign them to customers
- [Upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md): Prepare a CSV file and upload exact prices to one or more price lists
- [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md): Find a product and change or override its prices without a CSV file
- [Prices for one customer](https://docs.sparklayer.io/help/pricing/customer-pricing.md): Give individual customers their own price lists or an extra discount
- [Quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md): Set price breaks by quantity and price boxes, cases or pallets
- [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md): Set up order discounts, volume tiers and coupon codes (Growth plan)
- [How prices are shown](https://docs.sparklayer.io/help/pricing/pricing-display.md): Control how prices, RRP, savings and tax appear on your store
- [Pricing FAQs](https://docs.sparklayer.io/help/pricing/faqs.md): Answers to common questions, and how to diagnose pricing issues


---

# Price lists

URL: https://docs.sparklayer.io/help/pricing/managing-pricing

Create automatic or manual B2B price lists in SparkLayer, upload or override prices, and assign each list to the customer groups that should see it.

> **Quick summary**
>
> - A price list is a set of B2B prices matched to your product SKUs, in one currency. Create and manage them 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.
> - A price list can be **automatic** (a percentage off or on your Shopify prices, or another list), **manual** (exact prices you upload by CSV) or both. On the Pro and Enterprise plans, prices can also come from another system through the API.
> - Customers see a price list once it's assigned to their [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md), or to them individually with [customer pricing](https://docs.sparklayer.io/help/pricing/customer-pricing.md). If a group has several lists, the first one that contains the product wins: see [Which price list wins](#price-list-order).
> - The free Basic plan includes 3 price lists; Starter and above have unlimited price lists.

## How it works

You create price lists, then assign them to customers through [customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md). When customers sign in to your store, they see the prices you've set for them.

From pricing source to customer:

1. **Pricing source**: Your store's prices, a CSV file or another system
2. **Price list**: A rule such as 50% off, or exact prices per SKU
3. **Customer group**: Assign one or more price lists
4. **Customer**: Signs in and sees their prices

| Type | How it works | Best for |
| --- | --- | --- |
| **Automatic** | You choose a pricing source, such as your Shopify prices, and apply a percentage decrease or increase, such as 50% off. | A simple B2B pricing structure based on percentage discounts |
| **Manual** | You upload exact prices for your product SKUs by CSV, or edit them in the [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md). | Precise pricing, where you need control over every price a customer sees |
| **Integration** | A backend system such as an ERP, PIM or CRM sends price data to SparkLayer automatically. | Prices that are already managed in another system |

You can combine them: an automatic list at 50% off retail can also hold exact prices for a few products.

Prices are always shown **net** (excluding tax), and tax is added at checkout. To show prices with tax included, see [tax-inclusive price display](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-tax-inclusive-prices). If your store's own prices include tax, see [If your store's prices include tax](#tax-inclusive-prices) before you set up automatic pricing.

## Create a price list

Start with an empty price list, then add its prices. Before you start, check that:

- Every product you sell to B2B customers has a **unique SKU** in your store. Prices are matched to products by SKU.
- Those products are **active** in your store, not drafts. SparkLayer only imports prices for active products.
- You know the **currency** of the prices. You need one price list per currency.

To create a price list:

1. 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**.
2. Under **Details**, enter a **Name**, such as "Wholesale GBP".
3. Check the **Handle**. It's filled in from the name. You can change it now, but not later.
4. Choose a **Currency**. You can't change it later either.
5. Choose how the list gets its prices. Tick **Enable automatic pricing** for a percentage off your store's prices (see [Set up automatic pricing](#set-up-automatic-pricing)), **Enable manual pricing** to upload exact prices, or both.
6. Click **Save** in the save bar at the top of the page.

**More detail**

- Not sure which to choose? Automatic pricing is quickest if your B2B prices are a set percentage off your retail prices. Choose manual if you already have a spreadsheet of trade prices. You can upload exact prices to an automatic list later, so ticking both keeps your options open.
- If you've connected a backend system such as an ERP to SparkLayer, only create price lists by hand if they aren't imported from that system.

The new price list appears on the **Price lists** screen. Next:

1. Add its prices: [set up automatic pricing](#set-up-automatic-pricing), or [upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md).
2. [Assign the price list to a customer group](#assign-a-price-list-to-customers), so customers see it.

### Price list settings

The price list form has 3 cards: **Details**, **Automatic pricing** and **Manual pricing**.

**Every setting on the form**

| Setting | What it does |
| --- | --- |
| **Name** | The name shown in SparkLayer, for example "Wholesale pricing". It must be unique. You use it to assign the price list to a customer group. |
| **Handle** | The list's unique ID, for example `wholesale-pricing`. It's used in [bulk CSV uploads](https://docs.sparklayer.io/help/pricing/csv-upload.md#upload-prices-to-several-price-lists-at-once), [customer pricing](https://docs.sparklayer.io/help/pricing/customer-pricing.md) and the API. It can't be changed once the list is created. |
| **Currency** | The currency of the prices in the list, for example GBP. It can't be changed once the list is created. |
| **Enable automatic pricing** | Works out prices from a pricing source and your percentage, for example 50% off Shopify prices. |
| **Enable manual pricing** | Lets you set specific prices for each product by uploading a CSV file. Once a list is created, this card shows "Manual pricing is managed by uploading a CSV file on the price lists page." instead. |

### If you're on the Basic plan

Basic includes 3 price lists. If you save a 4th, you'll see **Basic includes 3 price lists**. Click **Try Starter free** to start a 14-day Starter trial with unlimited price lists, or click **Not now** and delete a list you don't use. See [Your plan and usage](https://docs.sparklayer.io/help/dashboard/plan-and-features.md).

## Set up automatic pricing

An automatic price list works out its prices from a **pricing source** and a percentage, so you don't set each price yourself. It's the quickest setup when your B2B prices are a set percentage off retail.

1. Create or edit a price list and tick **Enable automatic pricing**.
2. Choose a **Pricing source**: **Shopify Price**, or one of your other price lists.
3. Leave **Apply a percentage variation** ticked.
4. Choose **Decrease** or **Increase**, and enter the percentage. For example, to take 50% off, choose **Decrease** and enter `50`.
5. Click **Save** in the save bar.

**More detail**

- **Shopify Price** is the **Price** field on a product in the Shopify admin: the price your regular customers see on your store. When you change a price in Shopify, your automatic price lists update too.
- A decrease can be between 0% and 99%, and an increase between 0% and 500%.
- If the price list is in a different currency from its pricing source, set a [currency conversion](#set-a-currency-conversion). If your store's prices include tax, [adjust the percentage for tax](#tax-inclusive-prices).
- On other platforms, the pricing source is that platform's product price.

> **An automatic price list covers every product**
>
> An automatic price list always applies its percentage to all your products. You can't limit it to some SKUs, a brand or a collection. To price only some products, use a manual price list: upload a CSV with a `sku` and a `price` for just those products, or set them in the [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md). To add more SKUs later, upload a CSV with only the new ones. If a group has both kinds of list, the [order of its lists](#price-list-order) decides which price wins. For discounts by brand, see [Move brand discounts from another wholesale app](https://docs.sparklayer.io/help/guides/migrate-brand-discounts.md).

To set an exact price for a few products on an automatic list, upload them by CSV, or use **Override for this SKU** in the [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md#override-an-automatic-price-for-one-sku). The **Type** column then shows how many, for example **Automatic + 12 SKU**.

### Set a currency conversion

If the price list is in a different currency from its pricing source, you can set a fixed exchange rate. For example, if your pricing source is in USD and the price list is in EUR:

1. Tick **Currency conversion** ("Use a manual exchange rate").
2. Enter the rate, for example `1 USD = 1.1 EUR`.

If the price list is in the same currency as the pricing source, you can't set a currency conversion.

### If your store's prices include tax

SparkLayer treats the prices in a price list as **net** (excluding tax), and adds tax at checkout. An automatic price list takes its percentage off your store's own prices. So if your store's prices include tax, the result still contains tax, and tax is then added again at checkout. SparkLayer has no button to correct this for you: work out the percentage by hand, and enter that instead.

To find the percentage to enter as a **Decrease**:

1. Take your discount from 100. For 20% off: 100 − 20 = 80.
2. Divide that by 1 plus your tax rate. With 20% VAT: 80 ÷ 1.2 = 66.67.
3. Take the result from 100: 100 − 66.67 = 33.33. Enter `33.33` as the **Decrease**.

**Worked example: 20% off, with 20% VAT**

| Price | Amount |
| --- | --- |
| Your store's price, including 20% VAT | £120.00 |
| Net price (excluding VAT) | £100.00 |
| What you want trade customers to pay: 20% off the net price | £80.00 + VAT |
| With a **Decrease** of `20`, the price list price | £96.00 + VAT (20% off £120, treated as net) |
| With a **Decrease** of `33.33`, the price list price | £80.00 + VAT |

For trade prices with no discount, only the tax taken out, the decrease is 100 − (100 ÷ 1.2) = 16.67%.

On Shopify, your prices include tax when **Include sales tax in product price and shipping rate** is turned on at **Settings > Taxes and duties** ([open in the Shopify admin](https://admin.shopify.com/settings/taxes)). If it's off, your prices are already net and you can enter the percentage you want as it is. If your Shopify store uses line item tax (specific tax rates per SKU), automatic price lists don't take this into account.

On other platforms, the same applies whenever your platform's product prices include tax.

## Add manual prices

A manual price list holds the exact prices you set for each SKU. Choose the tool that fits the job:

| To | Use |
| --- | --- |
| **Add or update prices in bulk** | Click **Upload** next to the price list 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. See [Upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md). |
| **Change a few prices** | The [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md). |
| **Set price breaks by quantity** (for example buy 1 for $10.00, buy 5 for $8.00) | See [Quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md). |

You can add exact prices to an automatic price list too. That way you automate most of your pricing and still set specific prices for some products.

## Send prices from another system

If your prices are managed in a backend system such as an ERP, it can send them to SparkLayer automatically through the [SparkLayer API](https://docs.sparklayer.io/developers/api.md). This is available on the Pro and Enterprise plans, and is usually set up by your developer or integration partner. Some systems have a ready-made [integration](https://docs.sparklayer.io/help/integrations.md) that does this for you.

## Assign a price list to customers

A price list takes effect once you assign it to a [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md). This is how you decide which customers see which prices when they sign in.

1. 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 click the group's name. To set prices for every B2B customer, click **Edit** on the **Base customer group** card instead.
2. Find **Price lists**. If it's under **Inherited rules**, click **+ Override** next to it (on the base group, **+ Customize**) to move it up to **Customized rules**.
3. Choose a price list. To add another, click **Add price list**.
4. Click **Save** in the save bar.

**More detail**

- You can also choose a price list when you create a group, in the **Create customer group** window.
- **Reset** next to a customized rule hands it back to the base customer group.
- See [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md) for everything else a group controls.

### Which price list wins

A customer group can have several price lists, numbered in the order you add them. When a product is in more than one of them, the first list wins. As the group page puts it: "If a SKU is in more than one list, SparkLayer uses the first list it's in." So the order of the lists is their priority.

For example, if `ABC-123` is $10 in price list 1, $8 in price list 2 and $12 in price list 3, customers in the group see $10. A product that's only in list 3 gets its price from list 3.

- **Put the most specific list first**, such as a key account's prices or a clearance list, and a broad list like "Wholesale 30% off" last. A broad automatic list prices every product, so lists after it only count for products it can't price.
- **The order is the one shown in the group's Price lists rule**, at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app.
- **Prices from outside the group come first.** A customer's own price lists, set with [customer pricing](https://docs.sparklayer.io/help/pricing/customer-pricing.md), and a company's or location's price list, replace the group's. See [What overrides what](https://docs.sparklayer.io/help/customers.md#who-sets-what).

If a customer sees the wrong price, check the price list order on their group first. See [A customer gets prices from the wrong price list](https://docs.sparklayer.io/help/troubleshooting.md#a-customer-gets-prices-from-the-wrong-price-list).

### Prices for one company or customer

Customer groups set the prices for most buyers. When one business or person needs something different, set their prices at a lower level:

| For | Do this |
| --- | --- |
| **A company or one of its locations** | Choose a **Price list** on the [company page](https://docs.sparklayer.io/help/customers/companies.md#prices-and-rules) or the [location page](https://docs.sparklayer.io/help/customers/company-locations.md#prices-and-rules), in SparkLayer. |
| **One customer** | Give them their own price lists, or an extra percentage discount, on their record in your store (on Shopify, in the Shopify admin). See [Prices for one customer](https://docs.sparklayer.io/help/pricing/customer-pricing.md). |

For the whole job, step by step, follow [Give a key account their own prices](https://docs.sparklayer.io/help/guides/key-account-prices.md).

Once your price lists are set up and assigned, you manage them from the **Price lists** screen.

## The Price lists screen

**Pricing > Price lists** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/lists)), or **SparkLayer Wholesale > Pricing > Price lists** in the Shopify app is where you manage every price list. It lists them in a table, with **Bulk upload** and **Create price list** at the top.

| Column | What it shows |
| --- | --- |
| **Name** | The price list's name, with its handle underneath (for example "Handle: trade-20"). Click it to edit the list. |
| **Currency** | The list's currency, such as USD. |
| **Type** | **Manual (n)**: a manual list with n SKU prices. **Automatic + n SKU**: an automatic list with n SKUs set by hand. **Automatic**: an automatic list with no SKUs set by hand. |

Each row has an **Upload** button, for [uploading prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md), and a **⋯** menu.

**The ⋯ menu**

| Menu item | What it does |
| --- | --- |
| **Upload CSV** | Uploads prices to this list. See [Upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md). |
| **Download CSV** | Downloads the list's SKU prices as a CSV file. It's unavailable for an automatic list with no SKUs set by hand. |
| **Edit** | Opens the list's settings. |
| **Clear** | Removes every SKU price uploaded to the list. See [Clear or delete a price list](#clear-or-delete-a-price-list). |
| **Delete** | Deletes the list. See [Clear or delete a price list](#clear-or-delete-a-price-list). |

**Tips and shortcuts on the screen**

- A tip banner appears at the top of the screen when something needs attention, for example "Trade has no price list, so those buyers see retail prices." or "Trade 20% isn't used by any customer group yet."
- The **Common tasks** card links to the usual jobs: create a price list, change prices on a list, set the price of one product, choose who sees a price list, and upload prices from a spreadsheet.

## Edit a price list

1. 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 the list's name (or **Edit** in its **⋯** menu).
2. Change the **Name** or the automatic pricing. The **Handle** and **Currency** are read-only.
3. Click **Save** in the save bar.

The **More actions** menu at the top of the page has **Download CSV**, **Clear** and **Delete**.

## Clear or delete a price list

Clearing empties a list but keeps it; deleting removes it.

| Action | What happens |
| --- | --- |
| **Clear** | Removes every SKU price uploaded to the list. On an automatic list, the automatic rule stays. Confirm with **Clear prices**. |
| **Delete** | Deletes the list. Customer groups using it go back to your base pricing. This can't be undone. Confirm with **Delete price list**. |

Both are in the list's **⋯** menu 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 in **More actions** when you're editing the list.

## Tax and discounts

For how tax is calculated on B2B orders, see [Tax and shipping](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md).

To add promotions on top of price lists, use [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md) (Growth plan). They apply automatically or with a coupon code, for all customers or specific customer groups. They include an amount off an order, and volume tiers (more off as the quantity goes up).

## Show "price on application"

To show "Price on application" instead of a price, so customers contact you for one:

1. **Leave the product out of the customer's price lists.** With no B2B price, it shows **Unavailable** instead of a price and quantity box, and can't be added to the order. This needs manual price lists, because an automatic list covers every product. To do it for one group whatever its price lists, make the variant un-sellable for that group instead: see [Hide variants or make them unavailable](https://docs.sparklayer.io/help/storefront/product-display.md#hide-variants-or-make-them-unavailable).
2. **Rename "Unavailable".** At **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app, add overrides for `pdp.messaging.un-sellable` (product pages) and `product-card.messaging.un-sellable` (product cards), for example `Price on application`. See [Change the "Unavailable" message](https://docs.sparklayer.io/help/pricing/pricing-display.md#change-the-unavailable-message).

**More detail**

- The new text shows wherever a product has no price, including products missing from a price list by mistake. Check your other products have prices first: see [Why a product shows Unavailable](#unavailable).
- To let customers ask for a price, use the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md): your sales agents can add price on application (POA) products to a quote and set the price.

## Troubleshooting

**Diagnose: Product missing, no B2B price or “Unavailable”?** Find out whether it’s the product, the price list or your theme.

1. **What’s happening?** Sign in as a B2B customer, then pick the closest match.
   - The product says “Unavailable”, or shows the retail price: go to question 2
   - The product is missing completely: go to question 3
   - The product shows, but SparkLayer’s buttons or price are missing: go to question 4
2. **Search for the SKU in the Price editor. Does it find the product?** “No product was found for SKU” means SparkLayer doesn’t have it. Where to look: Pricing > Price editor (SparkLayer).
   - Yes: go to question 5
   - No product was found: go to question 3
3. **Does every variant of the product have a SKU?** Check each variant, not just the product. A barcode doesn’t count as a SKU. Where to look: Products > select the product (Shopify admin).
   - Yes: go to question 6
   - No: go to fix A (Add a SKU to every variant)
4. **Are SparkLayer’s buttons missing on every product, or just some?** Check a few products while signed in as a B2B customer.
   - Every product: go to fix B (This looks like a tags or theme issue)
   - Just some: go to question 7
5. **Does the product have a price in a price list on the customer’s group?** Without a B2B price, a product shows as Unavailable, or at your store’s own price. Where to look: Pricing > Price editor (SparkLayer).
   - Yes: go to question 8
   - No: go to question 9
6. **Is each SKU unique across your store?** If two variants share a SKU, SparkLayer can’t tell them apart. Where to look: Products (Shopify admin).
   - Yes: go to question 10
   - No / not sure: go to fix C (Make each SKU unique)
7. **Where are they missing?** Product pages and collection pages use different parts of your theme.
   - On the product page: go to question 11
   - On collection or search results pages: go to question 12
   - In a wishlist, quick view or other app: go to fix D (Other apps show your retail price)
8. **Is the customer trying to add fewer than the lowest tier in a tiered price list?** With tiered pricing, the lowest tier also sets the smallest quantity a customer can buy.
   - Yes: go to fix E (Add a tier for smaller quantities)
   - No: go to question 13
9. **Which type of price list should give it a price?** Manual lists are uploaded by CSV or set in the Price editor. Automatic lists work prices out from a pricing source, such as your Shopify prices. Where to look: Pricing > Price lists (SparkLayer).
   - Automatic: go to question 14
   - Manual (CSV): go to question 15
10. **Is the product’s status Active?** SparkLayer only imports active products, not Draft ones. Where to look: Products > select the product (Shopify admin).
   - Yes: go to question 16
   - No: go to fix F (Set the product to Active)
11. **Does this product use a different product template from the ones that work?** Check the Theme template setting on the product. Each template needs SparkLayer’s product widget. Where to look: Products > select the product (Shopify admin).
   - Yes: go to fix G (Add SparkLayer to this product template)
   - No / not sure: go to question 2
12. **Are you using a filter or search app on that page?** Filter and search apps often use their own product card, which needs SparkLayer added separately.
   - Yes: go to fix H (Add SparkLayer to the app’s product card)
   - No / not sure: go to fix I (Add SparkLayer to your product card)
13. **Does the variant’s `sparklayer.settings` metafield set `"sell": false` for this group?** That makes a variant visible but un-sellable on purpose. Where to look: Products > select a variant > Metafields (Shopify admin).
   - Yes: go to fix J (The variant is set not to be sold)
   - No / no metafield: go to fix K (Everything checks out)
14. **Does this variant have a value in the list’s pricing source?** For example, a list based on compare-at price needs a compare-at price on every variant. An empty field means there’s no B2B price. Where to look: Products > select the product (Shopify admin).
   - Yes: go to fix K (Everything checks out)
   - No: go to fix L (Fill in the pricing source)
15. **Did the SKUs change in Shopify after you uploaded the list?** Prices are matched by SKU, so a renamed SKU no longer matches its old row.
   - Yes: go to fix M (Update the price list with the new SKUs)
   - No / not sure: go to question 17
16. **Is the product published to the SparkLayer Wholesale sales channel?** Open the product and check its sales channels. Products from Shopify’s own Bundles app can’t be added to it. Where to look: Products > select the product (Shopify admin).
   - Yes: go to question 18
   - No: go to fix N (Add the product to the SparkLayer Wholesale sales channel)
   - I can’t select it (a bundle): go to fix O (Shopify’s own Bundles app isn’t supported)
17. **Do the SKUs in your CSV match Shopify exactly, with no spaces before or after?** Spreadsheet exports often add spaces. The upload succeeds, but nothing matches.
   - Yes: go to fix P (Add a price for this product)
   - No / not sure: go to fix Q (Trim the SKUs and upload again)
18. **Could the product be hidden on purpose, by B2B Catalogs or a visibility setting?** For example a `b2c-only` tag, or `"display": false` for the customer’s group.
   - Yes / not sure: go to fix R (Check what’s hiding it)
   - No: go to fix K (Everything checks out)

**Fixes**

- **A. Add a SKU to every variant** SparkLayer matches B2B prices to SKUs, so variants without one won’t show. Add a SKU and the product will appear after it syncs. Where: Products > select the product (Shopify admin).
- **B. This looks like a tags or theme issue** When SparkLayer’s buttons are missing on every product, the cause is usually the customer’s tags or your theme. Next: SparkLayer not showing or looking wrong?
- **C. Make each SKU unique** Rename duplicate SKUs so every variant has its own. Then update any price lists that use the old SKUs. Where: Products (Shopify admin).
- **D. Other apps show your retail price** Wishlist, quick view and search apps show Shopify’s own price and don’t know about B2B prices. A SparkLayer widget can be added to the app’s template instead. Ask us, or see the guide. See [Prices in other apps](https://docs.sparklayer.io/help/pricing/pricing-display.md).
- **E. Add a tier for smaller quantities** If the first tier starts at, say, 50, customers can’t buy fewer than 50. Add a price for a quantity of 1 if smaller orders should be allowed. Where: Pricing > Price editor (SparkLayer). See [Quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md).
- **F. Set the product to Active** Draft products don’t sync to SparkLayer. Set it to Active and allow a few minutes for it to sync. Where: Products > select the product (Shopify admin).
- **G. Add SparkLayer to this product template** Each product template needs SparkLayer’s product widget. Switch the product to your main template, or send us the template name and we’ll add it. Where: Products > select the product (Shopify admin).
- **H. Add SparkLayer to the app’s product card** Tell us which filter or search app you use and we’ll add SparkLayer’s product card widget to it.
- **I. Add SparkLayer to your product card** Your theme’s product card is missing SparkLayer’s widget, which often happens after a theme update. Send us a link to the page and we’ll add it.
- **J. The variant is set not to be sold** Remove `"sell": false` for this group, or change it to true, if customers in it should be able to buy it. Where: Products > select a variant > Metafields (Shopify admin). See [Product settings](https://docs.sparklayer.io/help/storefront/product-settings.md).
- **K. Everything checks out** Your setup looks right, so we'll take it from here. Send us your answers with the product link and the customer’s email.
- **L. Fill in the pricing source** The automatic list has nothing to calculate from, so the variant has no B2B price. Add the value, for example a compare-at price, and allow a few minutes for it to sync. Where: Products > select the product (Shopify admin). See [Automatic price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md).
- **M. Update the price list with the new SKUs** Rows for the old SKUs don’t match anything now. Upload the prices again with the new SKUs, or set them in the Price editor. Where: Pricing > Price lists (SparkLayer).
- **N. Add the product to the SparkLayer Wholesale sales channel** SparkLayer only imports products published to its sales channel. Where: Products > select the product (Shopify admin).
- **O. Shopify’s own Bundles app isn’t supported** Its bundle products can’t be published to the SparkLayer sales channel, so they get no B2B price or buttons. Use a bundle app that creates a regular product with its own SKU. See [Bundles and SparkLayer](https://docs.sparklayer.io/help/platforms/shopify/faqs.md#do-bundles-from-other-apps-get-b2b-prices).
- **P. Add a price for this product** Add the SKU to a price list on the customer’s group, or set it in the Price editor. If you don’t want B2B customers to buy it, hide it from them instead. Where: Pricing > Price editor (SparkLayer).
- **Q. Trim the SKUs and upload again** Clear the price list, remove spaces from the SKU column, save the CSV and upload it again. SKUs must match Shopify exactly. Where: Pricing > Price lists (SparkLayer). See [Upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md).
- **R. Check what’s hiding it** B2B Catalogs tags and the visibility metafield can hide products on purpose. Next: Product showing to the wrong customers?

### Why a product shows Unavailable

B2B customers see **Unavailable** instead of a price and quantity box when SparkLayer has no price it can use for them.

| Cause | Fix |
| --- | --- |
| **No B2B price for the SKU** on the customer's price lists. This is the most common cause. | Add a price for the SKU, by [CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md) or in the [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md). If B2B customers shouldn't buy it, hide it from them with the free [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-your-catalogs.md#make-a-product-b2b-only-or-b2c-only) app and the `b2c-only` tag. |
| **The automatic list's pricing source is empty** for that variant. For example, the list is based on the compare-at price and the variant has no compare-at price, so there's nothing to take the percentage from. | Fill in the field in your store, then wait a few minutes for it to sync. |
| **The SKU in the price list doesn't match the product**, because of spaces in the CSV or a SKU that's changed. | See [If prices show as Unavailable after an upload](#if-prices-show-as-unavailable-after-an-upload). |
| **The product isn't in SparkLayer.** The Price editor says no product was found. | Publish the product to the **SparkLayer Wholesale** sales channel, and check it's **Active**. See [Add prices for a product that isn't found](https://docs.sparklayer.io/help/pricing/price-editor.md#product-not-found). |
| **The variant has been made un-sellable** on purpose, with `sell: false` in its `sparklayer.settings` metafield. | Remove the setting if customers should be able to order it. See [Hide variants or make them unavailable](https://docs.sparklayer.io/help/storefront/product-display.md#hide-variants-or-make-them-unavailable). |

Your store might not say **Unavailable**. If your theme or the `pdp.messaging.un-sellable` [language string](https://docs.sparklayer.io/help/storefront/stock-display.md#change-stock-status-messages) has been changed, the same state can show as **Out of stock**, or as a message such as "Contact us to order". Check the causes above before you look at stock.

A free product from a [discount](https://docs.sparklayer.io/help/pricing/discounts.md) needs a B2B price too. If the free SKU has no price on the customer's price lists, it shows as Unavailable in the cart.

### If prices show as Unavailable after an upload

An upload can look successful and still match nothing. Two things cause this:

- **Spaces before or after a SKU.** `ABC-123 ` (with a space) doesn't match `ABC-123`. Clear the price list (**⋯** > **Clear**), trim the spaces from the SKU column, then upload the file again. In Excel or Google Sheets, the `TRIM` function removes them.
- **SKUs changed in your store after the upload.** The price list still holds prices for the old SKUs, so the products with new SKUs have no price. Upload the prices again against the new SKUs. See [Upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md).

## FAQs

**How quickly does an automatic price list update when I change a price in my store?**

Straight away. Price changes in your platform update automatic price lists in SparkLayer instantly.

**Can I override some prices in an automatic price list?**

Yes. Upload a CSV file to the automatic price list with only the SKUs and prices you want to set (see [Upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md)), or use **Override for this SKU** in the [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md).

**Can I change a price list's currency or handle?**

No. The handle and currency can't be changed once a price list has been created. Create a new price list instead.

**Where can I find more answers?**

See [Pricing FAQs](https://docs.sparklayer.io/help/pricing/faqs.md) for common questions about price lists, and the [troubleshooting guide](https://docs.sparklayer.io/help/troubleshooting.md) for ways to solve common issues.

## Next steps

- [Set up wholesale prices](https://docs.sparklayer.io/help/guides/set-up-wholesale-prices.md): The whole setup in one guide: a price list, a customer group and your first buyers
- [Upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md): Add exact prices to a price list from a spreadsheet
- [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md): Assign the price list to a group, then add customers to it


---

# Upload prices by CSV

URL: https://docs.sparklayer.io/help/pricing/csv-upload

Prepare a CSV file of SKUs and prices, upload it to one or several SparkLayer price lists, check the rows before you import, and update or remove prices.

> **Quick summary**
>
> - Upload exact prices to a price list with a CSV file that has a **SKU** and a **Price** column. Add `qty` for quantity pricing, `unit_of_measure` for unit of measure pricing, or `price_list_slug` to update several price lists at once.
> - Upload to one price list with **Upload** next to it 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, or to several with **Bulk upload** at the top of the same screen.
> - Before anything changes, **Check your upload** shows how many rows are ready and why any will be skipped. Then click **Import** to set the prices.
> - A file only needs the SKUs you want to change: everything else on the list stays as it is. Prices must be numbers, without a currency symbol.

## How it works

Upload a CSV file to set exact prices on a manual price list, or to set specific prices for some products on an automatic price list. For single changes, the [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md) is quicker.

A CSV (comma-separated values) file is a plain spreadsheet format. Any spreadsheet tool can save a sheet as a CSV file, usually from its **File** menu. In Google Sheets, for example, go to **File > Download > Comma Separated Values (.csv)**.

Uploading prices by CSV:

1. **Prepare the file**: One row per SKU and price
2. **Choose the file**: For one price list, or several with Bulk upload
3. **Check your upload**: See which rows are ready and which will be skipped
4. **Import**: Signed-in customers see the new prices

## Prepare your CSV file

Start from a template:

- [Download the CSV template](https://docs.sparklayer.io/files/price-list-template.csv): SKU and Price columns, ready to fill in
- [Copy our Google Sheet](https://docs.google.com/spreadsheets/d/13gi0W7yZcZ-CtWXYw1nUJN_art-gSbzRjqN8GSLNaig/copy): Makes your own copy in Google Drive

You can also get a template in the upload window: click **Download template**.

The simplest file has 2 columns, **SKU** and **Price**. It has a header row (the column names), then one row per SKU. Prices are per unit, for example `14.99`:

```csv
sku,price
123-abc,14.99
124-abc,12.99
125-abc,15.99
126-abc,99.99
```

The template writes the column names as `SKU` and `Price`. Column names aren't case-sensitive, so `sku` and `price` work too.

Before you upload, check that:

- The **price list exists**. If not, [create a price list](https://docs.sparklayer.io/help/pricing/managing-pricing.md#create-a-price-list) first.
- Every **SKU matches** a product SKU in your store exactly, and the product is active.
- No SKU has **spaces before or after it**. A space stops the SKU matching. In Excel or Google Sheets, the `TRIM` function removes them.
- The **header row** is the first row, and uses the column names shown below.
- **Prices are numbers only**, such as `14.99`, with no currency symbol.
- The file is **saved as CSV**, not as a spreadsheet file such as .xlsx.

### CSV columns

Most uploads need only SKU and Price. Add the other columns for specific features.

| Column | What it contains | Required |
| --- | --- | --- |
| `sku` | The product SKU as set up in your eCommerce platform or backend system. | Yes |
| `price` | The unit price for the SKU, for example `14.99`. Don't include a currency symbol such as $ or £. | Yes |
| `qty` | The quantity this price applies from, for [quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md). If you use it, every row needs a quantity, and every SKU needs a row with a quantity of `1`. An empty cell fails the import. Leave the column out and every price applies from a quantity of 1. | No (defaults to 1) |
| `unit_of_measure` | The unit the quantity belongs to, such as `box` or `pallet`, for [unit of measure pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md#set-up-unit-of-measure-pricing). Letters and numbers only, with underscores as separators, such as `pallet_box`. | No |
| `price_list_slug` | The handle of the price list to update, for [bulk uploads](#upload-prices-to-several-price-lists-at-once). | Only for bulk uploads |
| `display_tax_rate` | The tax percentage (0 to 100) used to show prices with tax included, for [tax-inclusive price display](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-tax-inclusive-prices). It applies to the whole SKU on the price list, so use the same rate on every row for a SKU: conflicting rates fail the import. A blank cell leaves the SKU's rate as it is, so you can give it on just one of its rows. | No |

For example, a file with price breaks, units and display tax rates:

```csv
sku,price,qty,unit_of_measure,display_tax_rate
ABC-123,10.00,1,each,20
ABC-123,9.00,10,each,20
```

## Upload prices to a price list

1. 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 **Upload** next to the price list (or **Upload CSV** in its **⋯** menu). The **Upload prices to** window opens, named after the list.
2. Choose your CSV file, or drop it into the window.
3. Under **Check your upload**, check the number of rows ready, and the reasons for any rows that will be skipped (see [Skipped rows](#skipped-rows)).
4. Click **Import**. The button shows how many prices it imports, for example **Import 240 prices**.

**More detail**

- Importing sets the prices for the SKUs in the file. Everything else on the list stays as it is.
- To fix a problem first, click **Choose another file**.
- If the price list isn't assigned to a customer group yet, [assign it](https://docs.sparklayer.io/help/pricing/managing-pricing.md#assign-a-price-list-to-customers) so customers can see the prices.

## Upload prices to several price lists at once

Use **Bulk upload** to update several price lists from one CSV file, for example the same products in several currencies.

1. Find the handle of each price list you want to update. It's shown under the price list's name 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, for example `Handle: base-uk`.

2. Add a `price_list_slug` column to your CSV file and enter the handle on each row. You can add as many rows as you need for each price list:

   ```csv
   sku,price,price_list_slug
   123-abc,7.99,base-uk
   123-abc,10.99,base-us
   789-abc,5.99,base-uk
   789-abc,7.99,base-us
   ```

3. 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, click **Bulk upload** at the top of the page. The **Bulk upload prices** window opens.

4. Choose your file, check the rows under **Check your upload**, then click **Import**.

Under **Check your upload**, the ready banner shows how many prices go to each list.

Once the prices are imported, [assign the price list to a customer group](https://docs.sparklayer.io/help/pricing/managing-pricing.md#assign-a-price-list-to-customers) if it isn't already.

## Skipped rows

Rows with a problem are skipped, and the rest still import. **Check your upload** shows your file's name and how many rows are ready, for example "238 of 240 rows ready", and lists each skipped row with a reason.

| Reason | What to do |
| --- | --- |
| **No SKU** | Add the SKU to the row. |
| **SKU … isn't in your catalogue** | Check the SKU exists in your store, matches exactly and the product is active. |
| **Price "…" isn't a number (no currency symbols)** | Enter the price as a number only, such as `14.99`. |
| **No price list with the handle "…"** | In a bulk upload, check the `price_list_slug` matches a list's handle exactly. |

If you see **This file can't be used**, the first row doesn't have the right column names. The first row needs **SKU** and **Price** (or **SKU**, **Price** and **price\_list\_slug** for a bulk upload). Click **Download template** to see the layout, then **Try another file**.

## Update or remove some prices

| To | Do this |
| --- | --- |
| **Update some prices** | Upload a CSV file with only the SKUs and prices you want to change. SparkLayer updates those prices and keeps the rest. |
| **Remove one product's price** | In the [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md), open the variant and click **Remove** next to the price. |
| **Remove every price from a price list** | Open the **⋯** menu next to the price list and click **Clear**, then **Clear prices**. On an automatic list, the automatic rule stays. |
| **Download a price list's prices** | Open the **⋯** menu next to the price list and click **Download CSV**. |

A row with a blank price doesn't remove that SKU's price. To remove a price, use the Price editor, or clear the price list.

## Troubleshooting

**My SKUs aren't found**

SparkLayer matches prices to products by SKU, so each product (variant) needs a unique SKU in your store. Check that:

- The **SKU exists** in your product catalogue and **matches exactly**.
- The SKU is **unique**.
- The product is **active**, not a draft.

See [Pricing FAQs](https://docs.sparklayer.io/help/pricing/faqs.md#why-isnt-my-b2b-pricing-showing-on-my-website).

**The upload worked, but products show as Unavailable**

The SKUs in the file probably don't match your products exactly. Check for:

- **Spaces before or after a SKU.** The upload can still look successful, but nothing matches. Clear the price list (**⋯** > **Clear**), trim the spaces from the SKU column, then upload the file again.
- **SKUs that changed in your store.** If you change a SKU after uploading its price, the price list keeps the old SKU and the product has no price. Upload the prices again against the new SKUs.

For other causes, see [Why a product shows Unavailable](https://docs.sparklayer.io/help/pricing/managing-pricing.md#unavailable).

**My prices aren't importing**

Check the price column contains numbers only, without a currency symbol, and that the header row is the first row of the file.

**Still having issues?**

See the [troubleshooting guide](https://docs.sparklayer.io/help/troubleshooting.md) for ways to solve common issues.

## Next steps

- [Assign a price list to customers](https://docs.sparklayer.io/help/pricing/managing-pricing.md#assign-a-price-list-to-customers): Choose which customer groups see the prices you've uploaded
- [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md): Check or change a single product's prices without a new file


---

# Price editor

URL: https://docs.sparklayer.io/help/pricing/price-editor

Use the SparkLayer Price editor to find a product or variant, see its price on every list, and edit, remove or override a price without a CSV file.

> **Quick summary**
>
> - The Price editor changes B2B prices one product at a time, without uploading a CSV file. Find it at **Pricing > Price editor** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/editor)), or **SparkLayer Wholesale > Pricing > Price editor** in the Shopify app.
> - Search for a product and open a variant to see its Shopify price and its price on every price list.
> - On a manual price list, edit or remove the price. On an automatic list, click **Override for this SKU** to set an exact price for that one variant.
> - For many prices at once, [upload a CSV file](https://docs.sparklayer.io/help/pricing/csv-upload.md).

## How it works

The Price editor is for one-off changes, such as giving one product a special price on your trade list. For changes to many products, [upload a CSV file](https://docs.sparklayer.io/help/pricing/csv-upload.md) instead.

The editor has 2 levels:

| Screen | What it shows |
| --- | --- |
| **Price editor** | A search box and a product table with **Product**, **ID or SKU** and **Retail price**. Click a product's arrow to show its variants underneath. |
| **A variant's prices** | The variant's details, its **Shopify price**, and a card for each price list with the variant's price on that list. |

It's also the quickest way to check whether a product has a price on a list, when [diagnosing pricing issues](https://docs.sparklayer.io/help/pricing/faqs.md#diagnosing-pricing-issues).

## Find a product's prices

1. Go to **Pricing > Price editor** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/editor)), or **SparkLayer Wholesale > Pricing > Price editor** in the Shopify app.
2. Search by product name, ID, barcode, variant SKU or option.
3. Click the arrow next to the product to show its variants. If you searched for a variant's SKU, the product opens already.
4. Click the variant's option name to see its prices.

**More detail**

- The variant's page shows the product name, its SKU and Shopify ID, and the option. Use the **Variant** menu to switch to another variant, or **View product in Shopify** to open it in your Shopify admin.
- **Shopify price** shows the variant's price in Shopify. It's read-only: change it on the product in Shopify.
- Each price list card shows the list's name and currency, and a table of **Quantity**, **Unit of measure** and **Price**.

## Edit or remove a price

You can edit a price on a manual price list, or on an automatic list you've overridden for this SKU.

1. Find the product and open the variant.
2. In the price list's card, click **Edit** next to the price.
3. Enter the new **Price for 1 or more** and click **Save price**.

To delete a price, click **Remove** next to it, then click **Remove price**. On an overridden automatic list, the SKU goes back to the list's automatic rule.

## Override an automatic price for one SKU

An automatic price list works out its prices from a rule, such as "Automatic: 20% off the Shopify price." To give one variant an exact price on that list:

1. Find the product and open the variant.
2. In the automatic list's card, click **Override for this SKU**.
3. Enter the **Price for 1 or more** and click **Save price**.

The card now says "Overridden for this SKU." 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, the list's **Type** counts the extra SKU, for example **Automatic + 1 SKU**. To go back to the rule, click **Remove** next to the price.

## Add a price

Add a price to give a variant a quantity break or a unit of measure price.

1. Find the product and open the variant.
2. Under the price list's table, click **Add a new price**.
3. Enter the quantity and price. For [unit of measure pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md#set-up-unit-of-measure-pricing), also enter the unit of measure.
4. Save the price.

## Add prices for a product that isn't found

If a search finds nothing, you'll see "No product was found for SKU …". You can still click **Create pricing for SKU …** to add prices for a SKU that isn't in your catalogue yet.

## FAQs

**Why can't I edit a price?**

The price is on an automatic price list, so it's worked out from the list's rule. Click **Override for this SKU** to set an exact price for that variant, or change the list's percentage 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. See [Set up automatic pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md#set-up-automatic-pricing).

**How do I add a product to a price list it isn't on?**

On a manual list, upload the product's SKU and price by CSV. See [Upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md). On an automatic list, every product already has a price from the rule.

**Where do I change the retail price?**

In Shopify. The **Shopify price** card is read-only and comes from the product in your Shopify admin. Automatic price lists based on it update when you change it.


---

# Prices for one customer

URL: https://docs.sparklayer.io/help/pricing/customer-pricing

Give individual B2B customers an extra percentage discount or their own price lists, set on the customer's record in Shopify or your other eCommerce platform.

> **Quick summary**
>
> - Give a single customer their **own price lists**, which replace their customer group's, or an **extra percentage discount** on top of their prices. Both are included on every plan.
> - Both are set on the customer's record in your eCommerce platform, in 2 SparkLayer fields called metafields: the customer's **price lists** and their **discount percentage**.
> - On Shopify, SparkLayer can add these fields to your store for you from **Integrations > Platform > Metafields** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Metafields** in the Shopify app. You then fill them in on the customer in the Shopify admin. Wix doesn't support metafields, so customer pricing isn't available on Wix.
> - To give a whole 
>   [company](https://docs.sparklayer.io/help/customers/companies.md)
>    different prices from its customer group, set the company's 
>   **Price list**
>    instead.

## How it works

A customer's prices usually come from the [price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md) assigned to their [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md). Customer pricing goes a step further for individual customers:

- **Customer-specific price lists** replace the customer group's price lists for that customer. For example, you have a standard B2B price list, but some customers should get lower prices on some or all products. You create another price list, upload its prices in SparkLayer, then set it on those customers.
- A **customer percentage discount** takes an extra percentage off the customer's prices. For example, your B2B customers are on a price list, and you want some of them to get an extra 25% off those prices.

How a customer's price is worked out:

1. **Customer group price lists**: The default for everyone in the group
2. **Customer price lists**: Override the group's, if set
3. **Customer discount**: An extra percentage off, if set

To choose between these, and a customer group of their own, step by step, follow [Give a key account their own prices](https://docs.sparklayer.io/help/guides/key-account-prices.md).

**Shopify only:**

People at a [company](https://docs.sparklayer.io/help/customers/companies.md) can also get a price list set on their company or location, in SparkLayer. See [Give a company its own price list](#give-a-company-its-own-price-list). A customer's own price lists win over their company's and location's: see [What overrides what](https://docs.sparklayer.io/help/customers.md#who-sets-what).

### Where customer pricing is stored

Customer pricing is stored in **metafields** (sometimes called attributes). A metafield is an extra field on a customer's record in your eCommerce platform, like a custom box on the customer's page, which SparkLayer reads. You set the field up once for your store, then fill it in for each customer who needs it.

See [Shopify metafields and data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md), and for other platforms, [Metafields](https://docs.sparklayer.io/developers/data/metafields.md) in the developer docs.

To check what a customer has, open their page at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app: **Price list override** is under **Basic information**, and **Discount percentage** under **Financial details**. Both are read-only there, because they come from your store.

## Give a customer their own price lists

A customer's own price lists replace their customer group's price lists.

1. Create the price list and add its prices. See [Price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md) and [Upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md).
2. Note the price list's handle, shown under its name 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, for example `vip-pricing`.
3. Make sure the `price_lists` metafield is set up in your store. On Shopify, you can add it from **Integrations > Platform > Metafields** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Metafields** in the Shopify app by clicking **Configure** next to **SparkLayer metafields**.
4. In the form below, enter the price list handles. It writes the value for you, for example `["vip-pricing","base-list"]`.
5. Click **Copy**, open the customer in your store admin (on Shopify, the customer's **Metafields** card), paste the value into the price lists field and save.

**Lots of customers? Fill them in one table (Shopify):** in your Shopify admin, go to **Customers**, tick the customers and click **Edit customers**. Click **Columns**, tick the SparkLayer field under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

**Metafield settings, if you create the field by hand**

The settings are the same on every platform:

| Setting | Value |
| --- | --- |
| **Custom data type** | Customers (on Shopify, at **Settings > Custom data > Customers** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data/customer/metafields))) |
| **Metafield type** | `json` |
| **Namespace** | `sparklayer` |
| **Key** | `price_lists` |
| **Value** | A JSON list of price list handles, as above |

For platforms other than Shopify, see the [SparkLayer developer docs](https://docs.sparklayer.io/developers.md).

## Give a customer an extra percentage discount

A customer discount takes an extra percentage off the customer's prices.

**Shopify:**

1. Set up the discount field once: go to **Integrations > Platform > Metafields** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Metafields** in the Shopify app, click **Configure** next to **SparkLayer metafields** and enable the customer discount. See [Add metafields automatically](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#add-metafields-automatically).
2. In your Shopify admin, go to **Customers** ([open in the Shopify admin](https://admin.shopify.com/customers)) and open the customer.
3. In the customer's **Metafields** card, find **Customer % Discount** (click **Show all** if you can't see it).
4. Enter the percentage, for example `25` for an extra 25% off, and save the customer.

**Lots of customers? Fill them in one table (Shopify):** in your Shopify admin, go to **Customers**, tick the customers and click **Edit customers**. Click **Columns**, tick **Customer % Discount** under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

**Metafield settings, if you create the field by hand**

| Setting | Value |
| --- | --- |
| **Custom data type** | Customers, at **Settings > Custom data > Customers** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data/customer/metafields)) |
| **Metafield type** | `number_decimal` |
| **Namespace** | `sparklayer` |
| **Key** | `discount_percentage` |
| **Value** | A decimal number, for example `10`, `22.5` or `50.25` |

**Other platforms:**

Set the `discount_percentage` metafield (or attribute) on the customer to the percentage, for example `25` for an extra 25% off. Your developer or agency can set this up with these settings:

| Setting | Value |
| --- | --- |
| **Custom data type** | Customers |
| **Metafield type** | `decimal` |
| **Namespace** | `sparklayer` |
| **Key** | `discount_percentage` |
| **Value** | A decimal number, for example `10`, `20` or `50` |

For more information, see the [SparkLayer developer docs](https://docs.sparklayer.io/developers.md).

For promotions such as coupon codes or spend thresholds, use [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md) instead.

## Give a company its own price list

**Shopify only:**

If you use [companies](https://docs.sparklayer.io/help/customers/companies.md), set a price list for the whole company instead of for each person in it. You do this in SparkLayer, not in your store.

1. Go to **Companies** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/companies)), or **SparkLayer Wholesale > Companies** in the Shopify app and click the company's name.
2. Under **Prices and rules**, choose a **Price list**. Leave it on **Use the customer group's price list** unless the company needs different prices from its group.
3. Click **Save** in the save bar.

## FAQs

**Does a customer's own price list replace their customer group's price lists?**

Yes. Price lists set on a customer override the price lists of their customer group.

**Can I set customer pricing from my ERP?**

Yes. Customer-specific price lists set with metafield data are designed for more advanced setups, such as pricing managed in an ERP. See [Send prices from another system](https://docs.sparklayer.io/help/pricing/managing-pricing.md#send-prices-from-another-system).

**Can I assign several price lists to a customer group instead?**

Yes. A customer group can have several price lists. See [Assign a price list to customers](https://docs.sparklayer.io/help/pricing/managing-pricing.md#assign-a-price-list-to-customers).


---

# Quantity pricing

URL: https://docs.sparklayer.io/help/pricing/quantity-pricing

Set up tiered quantity pricing and unit of measure pricing for boxes or pallets in SparkLayer, by CSV or in the Price editor, including rules for variants.

> **Quick summary**
>
> - **Quantity pricing** (also called tiered pricing or price breaks) lowers the unit price as customers buy more, for example 1 unit at $14.99, 5 at $10.99 and 10 at $8.99.
> - **Unit of measure pricing** prices set units such as boxes, cases or pallets, and works out the average unit price for the quantity ordered.
> - Set both up with prices you upload: a `qty` column (and `unit_of_measure`) in your [CSV upload](https://docs.sparklayer.io/help/pricing/csv-upload.md), or in the [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md). An automatic pricing rule can't create them.
> - Always include a price for a quantity of 1. Both features are available on every plan.

## How it works

With quantity pricing, the **unit price** depends on the quantity the customer adds to their order. SparkLayer finds the tier the quantity falls into and uses that tier's price. If the customer also has discounts, SparkLayer then takes them off the unit price.

For example:

| Quantity | Unit price |
| --- | --- |
| 1 or more | $14.99 |
| 5 or more | $10.99 |
| 10 or more | $8.99 |

Customers see the price breaks in the [Product Detail Interface](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md), as a table of **Qty**, **Price** and **Savings**. By default, the savings are worked out from the single unit price of the product or variant. To base them on the RRP (retail price) instead, see [How prices are shown](https://docs.sparklayer.io/help/pricing/pricing-display.md#base-savings-on-the-rrp).

## Set up quantity pricing

Quantity pricing works with prices you upload, not with an automatic pricing rule. On an automatic price list, upload prices for the products that need quantity pricing. See [Price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md).

1. Prepare a CSV file with `sku`, `price` and `qty` columns. Add one row per price break, and always include a row for a quantity of `1`:

   ```csv
   sku,price,qty
   123-abc,14.99,1
   123-abc,10.99,5
   ```

   Here, SKU `123-abc` costs 14.99 each from 1 unit and 10.99 each from 5 units.
2. 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 **Upload** next to the price list.
3. Choose the file, check the rows under **Check your upload**, then click **Import**. See [Upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md) for the full steps.

| Column | What it contains | Required |
| --- | --- | --- |
| `sku` | The product SKU as set up in your eCommerce platform or backend system. | Yes |
| `price` | The unit price for the SKU at the quantity in the `qty` column. | Yes |
| `qty` | The quantity from which this price applies. | No (defaults to 1) |

You must include a unit price for a quantity of `1`, even if customers can't buy single units because you've set up minimum quantities or pack sizes. See [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md).

To change quantity pricing for a single product, use the [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md): open the variant, then edit a price or click **Add a new price** to add another quantity break.

## Choose how variants are counted

For products with variants (for example colour or size), you choose whether quantities are counted across all variants or per variant.

| Behaviour | What happens |
| --- | --- |
| **Across all variants** (default) | Quantity pricing applies across every variant of the product. If a product comes in Small, Medium and Large and the price break starts at 5, a customer gets the lower price for any combination, such as 1 Small, 2 Medium and 3 Large. |
| **Per variant** | Quantity pricing only counts the quantity of each variant on its own. For example, you can set quantity pricing that only applies to the Large size. |

To count per variant, turn off **Tiered pricing across variants** at **Settings > Configurations > Pricing and cart** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Pricing and cart** in the Shopify app and save. The same switch is also at **Storefront > Options > Pricing and display** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Pricing and display** in the Shopify app; changing it in one place changes it in the other.

## Set up unit of measure pricing

Unit of measure pricing lets customers order in set units such as boxes, cases or pallets. You set a unit price for each unit, and SparkLayer prices any quantity left over at the single unit price.

It works like quantity pricing: customers buy more and pay less per unit. The difference is how the line total is worked out. SparkLayer splits the quantity across your units of measure, then adds up the line total. The unit price shown is the average across the total quantity.

For example, a product sells as single units, in boxes of 7 and on pallets of 150. A customer orders 320 units:

| Unit | Unit price | Units in the order | Line |
| --- | --- | --- | --- |
| Pallet (150 units) | $8.99 | 300 (2 pallets) | $8.99 × 300 = $2,697.00 |
| Box (7 units) | $10.99 | 14 (2 boxes) | $10.99 × 14 = $153.86 |
| Single unit | $14.99 | 6 | $14.99 × 6 = $89.94 |
| **Total** | | **320** | **$2,940.80** |

The unit price shown is $2,940.80 ÷ 320 = **$9.19**.

### Upload unit of measure prices

1. Prepare a CSV file with a `unit_of_measure` column as well as `sku`, `price` and `qty`. Set `qty` to the number of units in each unit of measure, and leave `unit_of_measure` blank for the single unit price:

   ```csv
   sku,price,qty,unit_of_measure
   123-abc,14.99,1,
   123-abc,10.99,7,box
   123-abc,8.99,150,pallet
   ```

2. Upload it to the price list from **Pricing > Price lists** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/lists)), or **SparkLayer Wholesale > Pricing > Price lists** in the Shopify app. See [Upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md).

| Column | What it contains | Required |
| --- | --- | --- |
| `sku` | The product SKU as set up in your eCommerce platform or backend system. | Yes |
| `price` | The unit price for the SKU at the quantity in the `qty` column. | Yes |
| `qty` | The quantity for this price. For a unit of measure, the number of units it contains. | No (defaults to 1) |
| `unit_of_measure` | The unit of measure the quantity belongs to. Use letters and numbers only, with underscores as separators, for example `box`, `pallet` or `pallet_box`. | No |

As with quantity pricing, you must include a unit price for a quantity of `1`, even if customers can't buy single units.

You can also set up unit of measure pricing in the [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md): add or edit a price, and enter the unit of measure and its unit price.

### How unit of measure pricing shows to customers

The [Product Detail Interface](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) shows the price for each unit, for example "1+", "7 (box)" and "150 (pallet)", and a breakdown of how the unit price has been calculated. The [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) shows the same breakdown, so customers can see how the line total and unit price were worked out.

## Show a quantity pricing table

SparkLayer shows your price breaks in the [Product Detail Interface](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) by default. To show the table anywhere else on your product page, add a code snippet. See [Show the quantity pricing table](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-the-quantity-pricing-table).

## Related quantity rules

Quantity rules control how customers order, rather than what they pay. See [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md). To combine price breaks, pack sizes and discounts for bigger orders, follow [Run volume pricing and promotions for trade customers](https://docs.sparklayer.io/help/guides/volume-discounts.md).

- **Pack sizes** (also called quantity increments): make customers add items in set packs, for example packs of 3 or 6.
- **Minimum quantities** for a variant (for example products that come in colours), or for the parent product as a whole, across its variants.
- **Maximum quantities** for a variant or for the parent product.

## For developers

These changes are made in code, so they're usually done by your developer or agency. You don't need them to set up quantity pricing.

### Name and pluralise units of measure

Language strings for each unit of measure let the storefront pluralise quantities in messages to customers (for example "1 box", "2 boxes"). Use the key you set for the unit of measure in your price list. Add the strings to your SparkLayer [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting):

```javascript title="Core Script"
translations: {
  en: {
    "unit-of-measure.unit-type.box": "{uomQuantity, plural, =1 {box} other {boxes}}",
    "unit-of-measure.unit-type.pallet_box": "{uomQuantity, plural, =1 {pallet box} other {pallet boxes}}"
  }
},
```

See [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md) for more on language strings that contain variables.

## FAQs

**Can I use quantity pricing with an automatic price list?**

Not from the automatic rule: quantity pricing needs prices you upload. Upload manual prices to the automatic price list for the products that need quantity pricing. See [Price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md).

**Do I need a price for a single unit?**

Yes. When you import a price list with quantity pricing, include a row for each SKU with a quantity of `1`, even if customers can't buy single units.


---

# Discounts

URL: https://docs.sparklayer.io/help/pricing/discounts

Set up B2B discounts in SparkLayer on the Growth plan: money off orders, volume tiers, coupon codes, customer group limits, scheduling and other requirements.

> **Quick summary**
>
> - SparkLayer discounts add promotions on top of your [price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md): an amount off an order, volume tiers (more off as the quantity goes up), free products and coupon codes. Manage them at **Pricing > Discounts** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/discounts)), or **SparkLayer Wholesale > Pricing > Discounts** in the Shopify app.
> - A discount applies **automatically** when the cart meets its requirements, or when the customer enters a **coupon code**. Limit it by customer group, dates, order sub-total, number of items, uses per customer, excluded customers and currency.
> - Discounts need the **Growth** plan or above, including the Growth trial. On Basic and Starter you can open the screens and fill in a discount, but saving it asks you to start Growth. See [Plan availability](#plan-availability).
> - Use SparkLayer discounts instead of your platform's own: Shopify discounts, BigCommerce promotions and Wix discounts can't be used alongside SparkLayer. See [Compare platforms](https://docs.sparklayer.io/help/platforms/compare.md).

Discounts sit on top of price lists, so you can run a promotion without changing anyone's prices. To try them as a customer, sign in to our [B2B demo store](https://demo.sparklayer.io/pages/b2b-login-register), add some products to your cart and use the coupon code `SAVE10`. New to SparkLayer? [Speak to our team](https://www.sparklayer.io/?demo#contact).

## How discounts work

Every discount has three parts:

- **A type and reward:** what the customer gets, such as 20% off the order or 5% off 24 or more units.
- **Requirements:** who qualifies and when, such as a customer group, a date range, a minimum spend or a coupon code.
- **How it's applied:** automatically, or when the customer enters a coupon code.

How a discount is applied to an order:

1. **Customer builds a cart**: Signed in, with their B2B prices
2. **Requirements checked**: Group, dates, coupon, order limits
3. **Reward applied**: To the net sub-total, before tax and shipping
4. **Order placed**: With the discount details saved on the order

| How it's applied | What happens |
| --- | --- |
| **Automatic** | SparkLayer applies the discount when the order meets the requirements you've set, for example spend over $1,000 and get $100 off. |
| **Coupon code** | SparkLayer applies the discount when the customer enters a coupon code in the [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md). See [Cart and checkout](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md) for what you can customise. |

### What a discount is calculated on

An amount off an order comes off the order's **sub-total**, which is net of tax and excludes shipping. For example, if the sub-total is $200.00 and the discount is $100 off, the cart shows "Discounts applied -$100". Tax is calculated in the final step of checkout.

Discounts apply whichever payment method the customer chooses. On Shopify, to give a discount for one payment method, add a [payment method rule](https://docs.sparklayer.io/help/ordering/payment-method-rules.md). Those discounts apply after all your other discounts, whatever their **Can be used with** setting.

### How many discounts apply to an order

By default, only one discount applies to an order. To let a discount be used alongside others, turn on its **Compatible discounts** requirement (see [Allow discounts to be combined](#allow-discounts-to-be-combined)).

## Discount types

Each discount has one type, which decides the reward the customer gets.

| Type | What it gives |
| --- | --- |
| **Give an amount off an order** | A percentage or fixed amount off the order's sub-total. This is the default. |
| **Give a free product** | Adds a product to the order at no cost. |
| **Give a percentage off products** | A percentage off specific products. |
| **Give a shipping reward** | Money off shipping, or a fixed shipping charge. Only available if you use SparkLayer [shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md). |
| **Advanced requirements and rewards** | For example volume tiers: more off as the quantity goes up. |
| **Advanced free products** | One or more free products when the cart meets requirements you set, such as "buy one get one free". |

## Create a discount

1. Go to **Pricing > Discounts** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/discounts)), or **SparkLayer Wholesale > Pricing > Discounts** in the Shopify app and click **Create discount**, or click a ready-made discount to start from it.
2. Under **Summary**, leave **Enable this discount** on.
3. Enter a **Discount internal name** (for you), a **Discount handle (or ID)** (a short unique ID, such as `vip-20-off`) and a **Discount public name** (what customers see). See [Summary settings](#summary-settings).
4. Under **Type**, choose a discount type. The **Reward** card changes to match.
5. Set up the reward. See the section for your type below.
6. Under **Requirements**, tick any requirements you need, such as **Coupon codes** or **Customer groups**. See [Limit who can use a discount and when](#limit-who-can-use-a-discount-and-when).
7. Click **Save** in the save bar.

To change a discount later, click its name at **Pricing > Discounts** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/discounts)), or **SparkLayer Wholesale > Pricing > Discounts** in the Shopify app, make your changes and click **Save**.

### Summary settings

| Setting | What it does |
| --- | --- |
| **Enable this discount** | Turns the discount on or off. A discount is only active when it's enabled and today falls within its schedule. |
| **Discount internal name** | A name for your own use. Only visible to you. |
| **Discount handle (or ID)** | Identifies the discount when an order is placed. It appears in the order's discount data (`discountSlugs`). |
| **Discount public name** | Shown to buyers when the discount applies to their order, for example "20% off your first B2B order". |

To show customers a longer description under the public name, your developer can add one: see [Show customers a description](#show-customers-a-description).

## Give an amount off an order

1. Create a discount and choose **Give an amount off an order** under **Type**.
2. Under **Reward**, choose **Percentage discount (e.g. 10% off)** or **Fixed amount discount (e.g. US$100 off)**.
3. Enter the **Percentage off** (between 1 and 100) or the **Amount off**.

The reward is applied to the order's sub-total, excluding tax and shipping ("net"). For a fixed amount, check the [currency requirement](#set-the-discount-currency).

## Set up volume tiers

Volume tiers give more off as the quantity goes up, for example 5% off 24 or more units and 10% off 96 or more.

1. Create a discount and choose **Advanced requirements and rewards** under **Type**.
2. Under **Reward**, set the first tier's **Minimum units** and **Discount** percentage. It starts at 24+ units and 5%.
3. Click **Add tier** for each further tier, and use the bin icon to remove one.

On the **Discounts** screen, these show with the type **Volume tiers**. To combine them with quantity pricing and pack sizes, follow [Run volume pricing and promotions for trade customers](https://docs.sparklayer.io/help/guides/volume-discounts.md).

## Give a free product, products off or a shipping reward

Set up these types the same way: choose the type under **Type**, then set up the reward.

| Type | What you set |
| --- | --- |
| **Give a free product** | The SKU of the product to add to the cart at no cost. It must be a valid SKU, and a different product from those already in the order. It also needs a price on the customer's price lists, or it shows as Unavailable. |
| **Give a percentage off products** | The SKUs to discount, and the percentage off each. |
| **Give a shipping reward** | The shipping method, and a percentage off, a fixed amount off, or a fixed charge. The amount is net of tax. |
| **Advanced free products** | The requirements the cart must meet, the free products and quantities, and whether they're added once, every time the requirements are met, or up to a limit. |

## Restrict a discount to certain products

Use a rule for a collection discount, or a discount on a product range or category. Under **Rules**, click **New rule** to add the products, collections or tags the cart must include before the discount applies.

For a tag-based discount, give every product in the range the same tag in your store, such as `dog-toy`, and choose that tag in the rule. This works for a range that isn't a collection.

## Limit who can use a discount and when

Requirements decide who gets a discount and when. A discount only applies when every requirement you've turned on is met.

The **Requirements** card lists 9 requirements, with a count of how many are on. Tick a requirement to turn it on, then set it up underneath.

| Requirement | Description on screen | Settings |
| --- | --- | --- |
| **Coupon codes** | Require a coupon code to use this discount | **Add a coupon code**, then **Add coupon** |
| **Customer groups** | Limit discount to specific customer groups | The **Customer groups** to include |
| **Scheduling** | Limit the discount to a specific date range | **Start date** and **Expiry date (optional)** |
| **Order sub-total limits** | Require a minimum or maximum order sub-total | **Minimum order sub-total** and **Maximum order sub-total** |
| **Order item limits** | Require a minimum or maximum number of items | **How to count the order**, **Require at least** and **Up to** |
| **Usage limits** | Limit number of uses per customer | **Maximum uses per customer** |
| **Exclude customers** | Exclude specific customers from this discount | The **Excluded customers** |
| **Compatible discounts** | Let this discount be used alongside others | The discounts it **Can be used with** |
| **Currency** | The buyer must be ordering in a specific currency | The **Currency** |

### Require a coupon code

A coupon code makes a discount manual: it isn't applied until the customer enters the code.

1. Tick **Coupon codes**.
2. Enter the code under **Add a coupon code** and click **Add coupon**. Add more codes the same way. Click **×** on a code to remove it.

With a coupon, the customer clicks **Discounts & codes** in the cart or the **Order Summary**, enters the code and clicks **Apply** (see [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md#discounts-and-promotions)). When the order reaches your store, the coupon codes used are in the order's additional notes (see [See discount details on an order](#see-discount-details-on-an-order)).

- Coupon codes are saved in capitals. For example, `Code-Abc` is saved as `CODE-ABC`.
- You can save several coupon codes against one discount, for example `CODE-ABC` and `CODE-123`, to promote the same discount in different places.
- The [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) accepts up to 3 coupon codes per order. If a customer has 3 coupons applied and adds a 4th, the 4th isn't applied.

### Limit a discount to customer groups

By default, a discount applies to all customers. To restrict it to some [customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md):

1. Tick **Customer groups**.
2. Tick one or more groups. Only these groups get the discount.

To apply the discount to everyone again, untick **Customer groups**.

### Schedule a discount

1. Tick **Scheduling**.
2. Choose a **Start date** and, if the discount should end, an **Expiry date (optional)**, each with a time.

- The dates use the time zone shown under them, for example Europe/London. For customers in another time zone, adjust the dates and times to match.
- A time of `00:00` means the start of the selected date, and `23:59` the end.

### Set minimum or maximum order requirements

**Order sub-total limits** set the spend needed to qualify, for example spend over $400 and get 5% off.

1. Tick **Order sub-total limits**.
2. Enter a **Minimum order sub-total**, a **Maximum order sub-total**, or both.

The discount applies when the order's sub-total (net of tax and shipping) is between these amounts. A maximum of 100 covers orders up to 99.99.

The amounts aren't converted between currencies. They're compared with the sub-total in the currency the customer orders in, even though the form shows your store's currency. A minimum of 5,000 means €5,000 for a customer on a EUR price list and 5,000 Kč for one on a CZK price list. If you sell in more than one currency, create one discount for each currency and limit each with [Currency](#set-the-discount-currency).

To give more off bigger orders without the discounts overlapping, make the ranges meet. For example, 1.5% off with a minimum of 5,000 and a maximum of 10,000, then 3.5% off with a minimum of 10,000. There's no setting to apply only the highest discount.

**Order item limits** set how many items the order must contain.

1. Tick **Order item limits**.
2. Under **How to count the order**, choose an option (see below).
3. Enter **Require at least**, **Up to**, or both.

| Option | What it counts | Example: 1 Red Shoe, 5 Blue Shoes, 4 Green Shoes |
| --- | --- | --- |
| **Quantity across all line items** | The total quantity of items across all products. | 10 |
| **Number of line items** | The number of different items (lines) in the order. | 3 |

### Limit uses per customer

1. Tick **Usage limits**.
2. Enter the **Maximum uses per customer**, for example `1` for a one-time discount.

Once a customer has used the discount this many times, it stops applying to their orders.

### Exclude customers

1. Tick **Exclude customers**.
2. Under **Excluded customers**, tick the customers who should never get this discount. Each is listed by name and company.

### Set the discount currency

If you have price lists in several currencies, you can limit a discount to one of them.

1. Tick **Currency**.
2. Choose the **Currency**, for example **GBP**.

The customer must be ordering in this currency for the discount to apply.

### Allow discounts to be combined

1. Tick **Compatible discounts**.
2. Under **Can be used with**, tick the discounts that can be used alongside this one in the same order. If you don't tick any, it can be combined with any discount.

Once your discounts are live, you manage them from the **Discounts** screen.

## The Discounts screen

**Pricing > Discounts** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/discounts)), or **SparkLayer Wholesale > Pricing > Discounts** in the Shopify app lists your discounts, with **Create discount** at the top.

| Column | What it shows |
| --- | --- |
| **Discount** | The discount's name, with a short description underneath, such as "Code TRADE10: 10% off" or "24+ units: 5% off, 96+ units: 10% off". Click it to edit the discount. |
| **Type** | **Order discount**, **Volume tiers** or **Coupon code**. |
| **Customer groups** | The groups the discount is limited to, or **All**. |
| **Status** | **Active** or **Paused**. |
| **Uses** | How many times the discount has been used. |

With no discounts yet, the screen offers two ready-made discounts you can edit before saving: **20% off with coupon code 20-OFF** and **$100 off orders over $1,000**.

## Pause or delete a discount

To stop a discount for now, pause it; to remove it for good, delete it. Open the discount from **Pricing > Discounts** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/discounts)), or **SparkLayer Wholesale > Pricing > Discounts** in the Shopify app and use **More actions** at the top of the page:

| Action | What happens |
| --- | --- |
| **Pause discount** | Stops the discount applying. Its status changes to **Paused**. Click **Turn on discount** to start it again. |
| **Delete discount** | Buyers stop getting it straight away. Orders that already used it keep their discount. This can't be undone. Confirm with **Delete discount**. |

## See discount details on an order

When a customer uses a discount, SparkLayer saves details of it on the order:

- The coupon codes applied.
- The handles (IDs) of the discounts applied.
- The order's value before the discount.
- The amount taken off by the discount.

All amounts are in the currency the customer ordered in.

**Shopify:**

The details are in the **Additional details** section of the Shopify order. You'll see:

- **B2B Discount Coupon Codes**: a comma-separated list of the coupon codes used, kept separate so you can see it at a glance.
- **B2B Discount Data**: the rest of the discount data, including the SKUs ordered, net pricing and the internal ID of the discount.

**Discount data for your developer**

In the Shopify API, the details are in `note_attributes`, and the discount data is a JSON string. For example:

```json
{"subTotalPreDiscount":{"net":"10.00"},"subTotalDiscount":{"net":"5.00"},"lineItemDiscounts":[{"preDiscount":{"net":"10.00"},"discount":{"net":"5.00"},"sku":"t-shirt","itemKey":"73199196ee530866c9a5db11f50c1442"}],"discountSlugs":["50-off"]}
```

To read this data with code, use the Shopify API (see the [Shopify Order API reference](https://shopify.dev/docs/api/admin-rest/latest/resources/order)).

**BigCommerce:**

The details are in the **Staff Notes** of the BigCommerce order. SparkLayer adds two lines to the notes of each order with a discount:

- **B2B Discount Coupon Codes**: a comma-separated list of the coupon codes used, kept separate so you can see it at a glance.
- **B2B Discount Data**: the rest of the discount data, as a JSON string.

To see them, go to **Orders** in your BigCommerce admin, click the three dots under **Action** next to the order, then click **View notes**.

To read this data with code, use the BigCommerce API (see the [BigCommerce Orders API reference](https://developer.bigcommerce.com/docs/rest-management/orders)).

**Other platforms:**

See the [SparkLayer developer docs](https://docs.sparklayer.io/developers.md) for how discount data is stored.

## Report on discount usage

SparkLayer doesn't have built-in reporting on discount usage.

**Shopify only:**

On Shopify, use [Shopify Flow](https://apps.shopify.com/flow), Shopify's automation tool, to tag orders that use a discount and then report on those tags. Download our [example Shopify flow](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/Tag_B2B_order_with_discount_if_used.flow?v=1723118334) and edit it to match your discounts. It works like this:

1. **An order is created** by the customer (for example a draft order). The flow starts on **Draft order created**.
2. **The flow checks for a discount** by looking at the **B2B Discount Data** field on the order (shown under **Additional details** in Shopify). It checks that a custom attribute key equals "B2B Discount Data" **and** its value includes a specific discount ID from `discountSlugs`, for example `free-product-test`.
3. **The flow tags the order**, for example with `b2b-free-product-test`, using **Add draft order tags**.
4. **You report on the tag**: filter the [Orders section](https://admin.shopify.com/store/orders?tag=b2b-discount-id) by the tag, or use the [Analytics section](https://admin.shopify.com/store/dashboards) in Shopify.

To find a discount's ID, edit the discount in SparkLayer and look at **Discount handle (or ID)**.

## Limitations

| Item | Limitation |
| --- | --- |
| **Combining discounts** | By default, a customer can only apply one discount to an order. Use [Compatible discounts](#allow-discounts-to-be-combined) to let discounts be used together. |
| **Payment-specific discounts** | You can't base a discount on the payment method, for example $10 off if the customer pays by card. |
| **Discounts from a URL** | You can't apply a discount from a link, for example $100 off for visiting `mystore.com/?discount=ABC`. |
| **Platform discounts** | Your platform's own discounts can't be used alongside SparkLayer (see [Compare platforms](https://docs.sparklayer.io/help/platforms/compare.md)). |

## Plan availability

Discounts are part of the **Growth** plan and above, including the 14-day Growth trial. Every discount type and requirement is included. See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md) and [SparkLayer pricing](https://www.sparklayer.io/pricing/).

On Basic and Starter:

- The **Discounts** screen shows **B2B discounts are part of Growth**. Click **Try Growth free** to start a trial.
- You can still open **Create discount** and fill it in. When you save, **Advanced discounts** opens: click **Try Growth free for 14 days** to start a trial and keep your discount, or **Book a 15-min demo**.

See [Your plan and usage](https://docs.sparklayer.io/help/dashboard/plan-and-features.md) for how trials work.

## For developers

These changes are made in your SparkLayer Core Script, so they're usually done by your developer or agency. You don't need them to set up or run discounts.

### Show customers a description

A discount description can be shown to customers when a discount is applied to their order, under its public name. For example: "For this month only, all customers will get 20% off their first order!" Add a language string of `discount.[handle].description` to your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting), replacing `[handle]` with the discount's **Discount handle (or ID)**. See [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md) for how language strings work.

```javascript title="Core Script"
/* [handle] should be replaced with the discount's handle,
shown in the discount's Summary card. */
translations: {
  en: {
    "discount.[handle].description": "Include a description here",
  }
},
```

### Change the cart text

To change the discount text customers see in the [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md), such as the coupon field's placeholder or the success message, add these language strings to your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting) and edit the values. See [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md).

```javascript title="Core Script"
translations: {
  en: {
     "cart.checkout.coupons.apply": "Apply",
     "cart.checkout.coupons.input-placeholder": "Enter discount code here and click 'Apply'",
     "cart.checkout.coupons.not-found": "Discount code ''{couponCode}'' not found",
     "cart.checkout.coupons.already-applied": "Discount code ''{couponCode}'' already applied",
     "cart.checkout.coupons.successful-apply": "You've successfully added discount code ''{couponCode}''!",
     "cart.checkout.coupons.max-reached": "You can only add a maximum of 3 discount codes",
     "cart.checkout.discount.cta": "Enter a discount here or view discounts",
     "cart.checkout.discount.success-message": "Discounts have successfully been applied to your order",
     "cart.checkout.discount.totals-row-text": "Discounts Applied",
     "cart.checkout.discount.no-of-discounts-applied": "{numberOf} {numberOf, plural, =1 {discount applied} other {discounts applied}}"
  }
},  
```

## Troubleshooting and FAQs

**I don't see the discount coupon box on the checkout**

The coupon field ("Enter discount code here and click 'Apply'") only shows to customers when there's an active, enabled discount that uses a coupon code. Check your discounts at **Pricing > Discounts** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/discounts)), or **SparkLayer Wholesale > Pricing > Discounts** in the Shopify app: the discount's **Status** should be **Active**, with **Enable this discount** on and a coupon code added.

**How do I see discount details on an order in my store?**

When a customer uses a discount, details are saved on the order in your store (for example Shopify or BigCommerce). See [See discount details on an order](#see-discount-details-on-an-order).

**Why wasn't a discount applied to an order?**

Check that:

- The discount is **Active**, not **Paused**, and **Enable this discount** is on.
- Today falls within its **Scheduling** dates, if it has them.
- The customer meets **every requirement** you've turned on: customer group, sub-total, items, usage and currency.
- The customer isn't in the **Excluded customers** list.
- The customer hasn't already applied another discount that it isn't **compatible** with.

**Will my B2B customers get my Shopify discount codes?**

No. Shopify discount codes and automatic discounts don't apply to orders placed through SparkLayer. Create the discounts you want B2B customers to get here, in SparkLayer. To keep a SparkLayer discount from particular customers, use the [Exclude customers](#exclude-customers) requirement. It's only available on SparkLayer discounts.

**Why isn't my free shipping discount applying?**

Check that:

- The discount **names the shipping method** the customer chose. A shipping reward only applies to the methods it names. If you have a method for each region, select each one, or create one discount per region.
- The customer is in one of the discount's **customer groups**, if you've limited it.
- The order meets the **minimum order sub-total**. The threshold is in the currency of the customer's price list: a minimum of 500 means £500 for a customer whose price list is in GBP.

To test it, [place a test order](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order) as the customer.

**Why can't I save a discount?**

- On Basic or Starter, saving opens **Advanced discounts**, because discounts need the Growth plan. See [Plan availability](#plan-availability).
- A message under a field tells you what's missing, such as "Give the discount an internal name", "Add a coupon code, or untick Coupon codes" or "Pick at least one customer group, or untick Customer groups".

**Can I discount a whole collection or product range?**

Yes. Add a rule under **Rules** with the collection, or with a tag that every product in the range shares. See [Restrict a discount to certain products](#restrict-a-discount-to-certain-products). For more off as the quantity goes up, use [volume tiers](#set-up-volume-tiers).

**How should I inform my customers about discounts?**

| Method | Details |
| --- | --- |
| **Email** | Send B2B customers emails about the discount codes, their benefits and how to use them. |
| **Website banner** | Show a banner on your homepage or relevant pages announcing the discount codes. |
| **Order confirmation** | Add a note to order confirmation emails or invoices reminding customers of codes for future orders. |
| **Sales reps** | Make sure your sales team tells B2B customers about discount codes when they talk to them. |
| **Printed materials** | Include discount codes in printed B2B marketing materials. |


---

# How prices are shown

URL: https://docs.sparklayer.io/help/pricing/pricing-display

Control how B2B prices appear on your store: RRP (MSRP), quantity price break tables, savings, price labels, unit costs, RRP-only mode and tax-inclusive prices.

> **Quick summary**
>
> - Change how prices appear to signed-in B2B customers: show an RRP (MSRP), price break tables and savings, tax-inclusive prices, custom price labels, a unit cost and an RRP-only mode.
> - Without code: show an **RRP** by filling in a field (a metafield) on each product variant, show **quantity price breaks** (they appear automatically), and turn on **Tax-inclusive prices** at **Settings > Configurations > Pricing and cart** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Pricing and cart** in the Shopify app. Wix doesn't support metafields, so RRP and unit cost display aren't available on Wix.
> - Savings and RRP options are switches at **Storefront > Options > Pricing and display** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Pricing and display** in the Shopify app: **Base savings on RRP**, **RRP toggle**, **Savings on price breaks** and **Round price break percentages**.
> - Everything else is a change to your SparkLayer **Core Script** or your theme, so it's usually done by your developer or agency. See [Customise how prices look](#customise-how-prices-look).

## How it works

Once your price lists are set up, SparkLayer's [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) show B2B prices on your store. You change what they show in 4 ways:

| Method | Use it for | How | Who usually does it |
| --- | --- | --- | --- |
| **Metafields** | Data stored per product variant, such as an RRP or a pack size | Set on the product in your eCommerce platform. See [Shopify metafields and data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md). | You, in your store admin |
| **Storefront options** | Switches for savings, the RRP toggle and price break percentages | Turn them on at **Storefront > Options > Pricing and display** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Pricing and display** in the Shopify app, then click **Save and publish**. See [Storefront options](https://docs.sparklayer.io/help/storefront/storefront-options.md). | You, in SparkLayer |
| **Core Script settings** | Display options (in `display`) and text (in `translations`) | Add code to your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting). See [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md) for changing text. | Your developer or agency |
| **CSS** | Colours and styling | Add CSS overrides. See [Customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md). | Your developer or agency |

## Show an RRP (MSRP) price

Show the RRP (recommended retail price, also called MSRP) next to a customer's B2B price, so signed-in customers see what retail customers pay and how much they save. For example, a product page might show "£6.75" with "RRP: £29.99" beside it. Each variant row shows its own RRP under its price.

Each variant's RRP is stored in a field called `rrp` (a metafield). SparkLayer adds the field for you, then you fill it in.

> **Filling in RRPs for your whole catalogue?**
>
> Follow [Show RRPs to your trade customers](https://docs.sparklayer.io/help/guides/show-rrp.md). It copies your Shopify prices with a ready-made Shopify Flow, or fills in every variant from a spreadsheet, so you don't type RRPs product by product.

To set an RRP on one product:

1. Set up the RRP field once. On Shopify, go to **Integrations > Platform > Metafields** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Metafields** in the Shopify app and click **Configure** next to **SparkLayer metafields**. On other platforms, see the field details below.
2. In the form, enter the RRP and its currency, for example `15.99` and `usd`. Add a row for each currency you sell in. It writes the value for you.
3. Click **Copy**, open the variant in your store admin, paste the value into the `rrp` field and save.

The RRP is set on each variant, as a decimal amount such as `9.00` (not in pence or cents), with one entry per currency: `[{"value":9.00,"currency_code":"gbp"}]`.

On a product with several variants, the RRP in the product summary is the RRP of the first variant, in your platform's variant order. It doesn't change when the customer picks another variant, and it can't show a range yet. Each variant's own RRP shows in the variant table.

**Field details**

| Setting | Value |
| --- | --- |
| **Custom data type** | Variants. On Shopify, at **Settings > Custom data > Variants** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data/productvariant/metafields)) |
| **Metafield type** | `JSON` |
| **Namespace** | `sparklayer` |
| **Key** | `rrp` |
| **Value** | `[{"value":15.99,"currency_code":"usd"}]`, where `value` is the retail price and `currency_code` is the currency code (for example `usd`, `gbp` or `eur`). For more currencies, add more entries: `[{"value":15.99,"currency_code":"usd"},{"value":10.99,"currency_code":"gbp"}]` |

## Show the quantity pricing table

If you've set up [quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md), SparkLayer shows the price breaks in the [Product Detail Interface](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) by default, as a table with **Qty**, **Price** and **Savings** columns.

Customers also see a **Qty discount pricing** table, and the price per unit, when they add items to the [My Cart Interface](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md).

To show an extra price breaks table anywhere on your product page, make a small change to your theme's product page code:

**Theme code for your developer**

Add this to the source code of your product pages:

```html
<spark-variant-price-breaks
  variant-sku="{{ product.selected_or_first_available_variant.sku }}"
  parent-id="{{ product.id }}"
>
</spark-variant-price-breaks>
```

For minimum quantities, pack sizes and other quantity settings, see [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md).

## Show tax-inclusive prices

Tax-inclusive price display shows your B2B prices with tax included, labelled "inc. tax" so buyers know what they're seeing. It's designed for markets where buyers expect gross prices, which is common in Australia and in trade sectors that sell to smaller businesses.

> **Tax-inclusive display changes presentation only**
>
> Your prices are still stored, uploaded and charged net. The tax your buyer pays is still calculated by your store's checkout at the point of purchase, using the rules or third-party integration set up in your eCommerce platform.

If your store's own prices include tax and you use automatic price lists, that's a different setting: see [If your store's prices include tax](https://docs.sparklayer.io/help/pricing/managing-pricing.md#tax-inclusive-prices).

How it works:

- **It shows gross prices** to buyers who think in tax-inclusive terms, without changing how you upload or charge for your pricing.
- **It works per price list.** Turn it on for the price lists that need it and leave the rest showing net prices, so you can serve different markets from one store.
- **It uses your own rate per product.** You supply a display tax rate per SKU, so reduced-rate and zero-rated products show correctly next to standard-rate ones.
- **It labels prices.** Key pricing areas add an "inc. tax" label, so it's clear which basis a buyer is seeing.

### Turn on tax-inclusive display

Buyers only see gross prices once all 3 parts are in place.

1. **Turn it on for your store.** Go to **Settings > Configurations > Pricing and cart** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Pricing and cart** in the Shopify app, turn on **Tax-inclusive prices** and click **Save**.
2. **Turn it on for each price list.** Each price list has its own **Tax Inclusive Display** setting. The setting only shows on manual price lists, because the rate comes from your CSV. Automatic price lists don't have it. Turn it on for the price lists whose customers should see gross prices. Customers on other price lists keep seeing net prices.
3. **Add a display tax rate to your products.** Add a `display_tax_rate` column to your [price CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md): the percentage used to work out the gross price from your net price, from 0 to 100. Use the same rate on every row for a SKU. For the columns and an example file, see [CSV columns](https://docs.sparklayer.io/help/pricing/csv-upload.md#csv-columns).

```csv
sku,price,display_tax_rate
ABC-123,10.00,20
```

A product on a tax-inclusive price list with **no rate, or a rate of 0**, still shows the "inc. tax" label, at 0%. This is deliberate, so a zero-rated product can't be confused with one whose rate hasn't been uploaded yet.

### Where buyers see tax-inclusive prices

Once it's on, gross prices and the "inc. tax" label appear at every step of buying.

| Area | What buyers see |
| --- | --- |
| **Product pages and product cards** | The gross price, with the label next to key pricing information. The label isn't repeated for every price in pricing tables. Where a product has several prices, the "from" price follows whichever price applies. |
| **Cart** | Each line shows its gross line total, and the cart subtotal and total show gross with the label. The shipping message reads "Prices include tax. Shipping costs calculated during checkout" instead of the standard net wording. |
| **Checkout** | The order total on the checkout review step shows gross with the label. Minimum and maximum order value rules are checked against the gross total, so buyers are measured against the total they can see. |
| **Order history** | In the customer's account area, order lines and the order total show on the same basis, so a past order looks the way the buyer bought it. |

### Limitations of tax-inclusive display

Tax-inclusive display only suits stores with simple tax setups, where you can always provide a tax rate for each SKU on a tax-inclusive price list. Read these limits before you turn it on.

| Limitation | What it means |
| --- | --- |
| **Your store's checkout decides the tax charged** | The display tax rate you upload is only used for display; the actual tax is calculated by your store's checkout. If the two differ, your buyer sees one figure in the cart and pays another. Keep your uploaded rates in line with your store's tax setup. |
| **Tax-exempt customers always see net prices** | If a customer is marked as tax exempt, SparkLayer shows them net prices with no label, whatever the price list setting, because a gross price would be wrong for them. |
| **Mixed carts show net totals** | If a cart has both tax-inclusive and tax-exclusive products, the cart totals show net and drop the label. Each line still shows on its own basis. A single gross total across both would understate the tax on the tax-exclusive lines. |
| **Custom items and unpriced products affect cart totals** | Custom line items have no display tax rate. A cart containing a product with no price but a manually quoted price shows net totals. |
| **Quoted prices are always net** | When a sales agent edits a quoted unit price, it's entered and stored net. The editor is labelled "(excluding tax)" when the prices around it are shown gross. |
| **RRP prices are never adjusted for tax** | RRPs show exactly as you upload them. On a tax-inclusive price list, a gross B2B price sits next to a net RRP, and any savings percentage based on the RRP compares the two. If you show both, upload RRPs on the same basis as your display prices. |
| **Display can vary within a product** | Variants of the same product can use different price lists, so one variant may be tax-inclusive and another not. Set up your price lists and customer groups so customers only see either tax-inclusive or tax-exclusive prices. |

## Show B2B prices in other apps

Wishlist, quick view, search and upsell apps show your platform's own price: the retail price, with tax included if your store shows it that way. They don't know about SparkLayer, so they can't show B2B prices on their own.

To show a B2B customer their price inside one of these apps, your developer embeds a SparkLayer interface in the app's template, if the app lets you edit it:

| To show | Use |
| --- | --- |
| **The price only** | `spark-product-price` (and `spark-product-rrp` for the RRP). See [Product price](https://docs.sparklayer.io/help/storefront/interfaces/product-price.md). |
| **The price with a quantity box and an add button** | `spark-product-card`, or `spark-product-card mode-quick-buy` for a quick buy row. See [Product card](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) and [quick buy mode](https://docs.sparklayer.io/help/storefront/product-display.md#turn-on-quick-buy-mode). |

The app's own quantity selectors and add-to-cart buttons don't add to the SparkLayer cart, so hide them for B2B customers. If you'd like us to set this up for you, [contact our support team](https://docs.sparklayer.io/help/support.md).

## Discounts and promotions

To show discounts and promotions in the cart, set them up in [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md) (Growth plan). They apply automatically, or with a coupon code during checkout.

## Customise how prices look

Change what the price labels say, how the RRP and savings look, and what shows when a product has no price. Several of these are switches at **Storefront > Options > Pricing and display** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Pricing and display** in the Shopify app, which need no code. The rest are made in your SparkLayer [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting), your CSS overrides or your theme's code, usually by your developer or agency. For how language strings (`translations`) work, see [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md).

### Change the RRP label

To change the "RRP" label, for example to "MSRP", add this to your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting):

```javascript title="Core Script"
translations: {
  en: {
    "pdp.price.rrp": "MSRP: ",
    "product-card.price.rrp": "MSRP: ",
    "cart.price.rrp": "MSRP: ",
  }
},  
```

### Style the RRP

To change how the RRP looks, for example to strike it through in red, add this CSS to your [CSS overrides](https://docs.sparklayer.io/help/storefront/customising-design.md) and adjust it as needed:

```html
<style>
:root {
   --spark-pricing-rrp-decoration: line-through;
   --spark-pricing-rrp-color: red;
}
</style>
```

### Change how savings are shown

You can change the **Savings** column in quantity pricing tables at **Storefront > Options > Pricing and display** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Pricing and display** in the Shopify app, then click **Save and publish**:

| Switch | What it does |
| --- | --- |
| **Savings on price breaks** | Shows the amount saved next to each quantity break. On by default. |
| **Round price break percentages** | Shows savings as whole-number percentages, for example 9% off instead of 9.45% off. On by default. |

**The same settings in the Core Script**

```javascript title="Core Script"
display: {
  roundPriceBreakPercentages: true,
  showPriceBreakSavings: false,
}
```

`showPriceBreakSavings: false` hides the savings.

### Base savings on the RRP

By default, the savings in a quantity pricing table are calculated from the **single unit price** of the product or variant. For example, if the single unit price is $2.00 and the price drops to $1.00 for 5 or more, the savings show as `-50%`.

To calculate savings from the product's **RRP** (retail price) instead, turn on **Base savings on RRP** at **Storefront > Options > Pricing and display** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Pricing and display** in the Shopify app and click **Save and publish**. For example, with an RRP of $21.95 and a price of $16.66, the savings show as -24% from the first price break.

**The same setting in the Core Script**

```javascript title="Core Script"
display: {
  savingsUseRrp: true,
}
```

### Change the price labels

You can add text before the price on a product page, such as "Your price", so it reads "Your Price, from: £2.91". Add this to your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting):

```javascript title="Core Script"
translations: {
  en: {
    "pdp.price.from-prefix": "Your Price:"
  }
},
```

You can also change any of the default pricing text with these language strings:

```javascript title="Core Script"
translations: {
  en: {
    "pdp.price.from": "From:",
    "pdp.price.rrp": "RRP:",
    "pdp.price.pack-size": "Pack ({packSize}): {price}",
    "product-card.price.from": "From:",
    "product-card.price.rrp": "RRP:"
  }
},
```

### Show a unit cost price

If you sell products made up of several units, you can show a unit price on your product pages, worked out automatically. For example, a product sold in packs of 10 could show "This product comes in packs of 10. Unit cost $0.31". Or, for products sold by weight, you could show a price per kg.

To set it up, add a `case_size` metafield to each product variant.

**Shopify:**

See [Shopify metafields and data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md) for how to set up metafields on Shopify.

| Setting | Value |
| --- | --- |
| **Custom data type** | Variants, at **Settings > Custom data > Variants** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data/productvariant/metafields)) |
| **Metafield type** | `integer` |
| **Namespace** | `sparklayer` |
| **Key** | `case_size` |
| **Value** | A whole number, for example `1`, `2` or `3` |

Then add this code to your product page template and change it as needed:

**View code sample**

```javascript
{%- if customer.metafields.sparklayer.authentication -%}

  {% if product.metafields.sparklayer.case_size %}
  <span data-custom-spark-case-size="{{ product.metafields.sparklayer.case_size }}" data-product-id="{{ product.id }}"></span>

  <script>
      document.addEventListener('DOMContentLoaded', function(event) {
        setTimeout(() => {
        document.querySelectorAll('[data-custom-spark-case-size]').forEach(async (el) => {
          var caseSize = Number(el.dataset.customSparkCaseSize);
          if (!caseSize) {
             return;
          }
          var productId = el.dataset.productId;
          try {
            priceData = await window.spark.getPriceForProduct (productId);
          } catch (e) {
            console.error(e);
            return;
          }
          const formatter =	new Intl.NumberFormat([], {
            style: 'currency',
            currency: priceData.currencyCode ?? 'usd',
          });
          el.textContent = `This product comes in packs of ${caseSize}. Unit price ${formatter.format(priceData.fromPrice / Number(caseSize))}`;
        });
        }, 500);
      });
  </script>

  {% endif %}

{% endif %}
```

**Use Shopify's unit price feature**

If you use Shopify's built-in unit price (in the product's pricing, tick **Show unit price for this product** and set the **Total product measurement** and **Base measure**, such as 400 g and 1 kg), you can show the reference unit, such as kg, lb or ml. In the code sample above, change `el.textContent` to:

```javascript
el.textContent = `Unit price per {{ item.unit_price_measurement.reference_unit }}:  ${formatter.format(priceData.fromPrice / Number(caseSize))}`;
```

To customise how this works further, we recommend working with a Shopify expert.

**Other platforms:**

| Setting | Value |
| --- | --- |
| **Custom data type** | Variant level (products) |
| **Metafield type** | `integer` |
| **Namespace** | `sparklayer` |
| **Key** | `case_size` |
| **Value** | A whole number, for example `1`, `2` or `3` |

For more information, see the [SparkLayer developer docs](https://docs.sparklayer.io/developers.md).

### Change the "Unavailable" message

When a product has no B2B price, the [Product Card Interface](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) and [Product Detail Interface](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) show "Unavailable", so B2B customers know they can't buy it. To show a different message, such as "Price on application", add a translation override for each key below at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app. No code is needed. For the full recipe, see [Show "price on application"](https://docs.sparklayer.io/help/pricing/managing-pricing.md#price-on-application).

| Key | Default text |
| --- | --- |
| `pdp.messaging.un-sellable` | Unavailable |
| `product-card.messaging.un-sellable` | Unavailable |
| `product-card.messaging.select-option` | Unavailable, please select another option |

A developer can set the same text in your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting) instead:

```javascript title="Core Script"
translations: {
  en: {
    "pdp.messaging.un-sellable": "Unavailable",
    "product-card.messaging.un-sellable": "Unavailable",
    "product-card.messaging.select-option": "Unavailable, please select another option"
  }
},
```

### Show RRP prices only

If you take orders with customers in person, for example in a shop, you can make the SparkLayer [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) show only the RRP (MSRP) while browsing and adding items to an order. This hides your B2B prices from view.

Use cases include:

- In-store customer visits, where an order needs to be placed and the customer must only see retail (RRP) prices.
- Sales teams placing orders on behalf of customers (for example on the road), where only retail (RRP) prices must be seen.

This is for display only. The order is still created with the B2B prices of the signed-in customer.

To turn it on for every B2B customer who signs in, turn on **RRP toggle** ("Buyers can switch between the RRP and their own prices.") at **Storefront > Options > Pricing and display** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Pricing and display** in the Shopify app and click **Save and publish**. Or add this to the `display` section of your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting):

```javascript title="Core Script"
display: {
  showRrpToggle: true,
}
```

**Shopify only:**

To turn it on only for some customers, check their tags (Shopify Liquid):

```javascript title="Core Script"
display: {
{% for tag in customer.tags %}
 {% if tag == "b2b-group-1" %}
  showRrpToggle: true,
 {% elsif tag == "b2b-group-2" %}
  showRrpToggle: true,
 {% endif %}  
{% endfor %}

}
```

## FAQs

**Does tax-inclusive display change the prices I upload or the amount my customer is charged?**

No. Prices are stored and charged net exactly as before, and your checkout calculates tax as it always has. Only the figure shown on your store changes.

**Can I show tax-inclusive prices to some customers and not others?**

Yes. Tax-inclusive display is set per price list, so you can show gross prices to the customer groups on one price list and net prices to everyone else.

**What happens if I don't upload a display tax rate?**

Products on a tax-inclusive price list with no rate show their net price, still labelled "inc. tax", at an effective 0%. Upload rates for every product on a tax-inclusive price list so buyers see accurate gross prices.

**Why does my cart total show net when my product prices show gross?**

The cart most likely contains a mix of tax-inclusive and tax-exclusive products, a custom item, or a product with a quoted price and no uploaded price. In these cases the cart totals show net rather than a gross figure that would understate the tax due. Set up your price lists and customer groups so a customer sees only tax-inclusive or only tax-exclusive price lists, not a mixture.

**Will my buyers see gross prices at card checkout?**

The SparkLayer cart and checkout review show gross prices with the label. Once a buyer moves into your store platform's own checkout, that platform's tax display rules apply.

**Why don't RRP or unit cost prices show on my Wix store?**

**Wix only:**

Both rely on product metafields, which can't be set up in Wix. See [Wix limitations](https://docs.sparklayer.io/help/platforms/wix/limitations.md).


---

# Pricing FAQs

URL: https://docs.sparklayer.io/help/pricing/faqs

Answers to common SparkLayer pricing questions on automatic and manual price lists, tiered pricing, gross prices and currencies, plus diagnosing pricing issues.

## Setting up prices

**Do I need product SKUs when uploading pricing?**

Yes. SparkLayer matches prices to products by SKU. Without a unique SKU in your store (for example Shopify), a product can't show the right B2B price when customers sign in.

**Why isn't my B2B pricing showing on my website?**

Check that:

- You've **imported a price list** 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 **assigned it to a customer group** at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app.
- All your products have **unique SKUs**.
- The **SKU exists** in your product catalogue.
- The product's status in your store admin is **Active**. SparkLayer only imports prices for active products, not products in **Draft** status.

Then follow the steps in [diagnosing pricing issues](#diagnosing-pricing-issues).

**How do I show the gross price?**

Turn on **Tax-inclusive prices** at **Settings > Configurations > Pricing and cart** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Pricing and cart** in the Shopify app. It shows gross prices, labelled "inc. tax", on the price lists you choose. Prices are still charged net, and tax is calculated at checkout. See [tax-inclusive price display](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-tax-inclusive-prices).

By default, SparkLayer shows prices net (excluding tax), whatever tax setting you use on your store. Customers see exactly the prices you upload.

Some merchants use a workaround instead:

1. Set the customer as tax exempt in your eCommerce platform (for example Shopify), so their orders are zero-rated for tax.
2. In the price lists you upload to SparkLayer, enter gross amounts (even though they don't technically include tax).
3. Report on the tax amounts afterwards, for example in your accounting system.

**How do I show RRP (MSRP) pricing?**

Add an `rrp` metafield to your product variants. See [Show an RRP (MSRP) price](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-an-rrp-msrp-price).

**How do I set up and manage several currencies?**

SparkLayer supports several currencies by default: create a price list in each currency and assign it to the right customers. On Shopify, see [Shopify Markets and currencies](https://docs.sparklayer.io/help/platforms/shopify/markets-and-currencies.md).

**Can I set B2B prices higher than my retail (DTC) prices?**

Yes. Use a percentage increase on an automatic price list, or upload the higher prices.

**Can I set up different automatic pricing rules based on product collections?**

Not directly: SparkLayer has no built-in way to apply B2B pricing to selected collections (or categories). As a workaround:

1. Create a [separate price list](https://docs.sparklayer.io/help/pricing/managing-pricing.md#create-a-price-list) for each collection you need (Collection A, Collection B and so on).
2. At **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app, assign the price lists each customer group should see. You can assign **several** price lists to a customer group.

## Automatic price lists

**How do I set up automatic price lists (based on my retail prices with a discount)?**

Create a price list and tick **Enable automatic pricing**, choose your store's prices as the pricing source and apply a percentage variation. See [Set up automatic pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md#set-up-automatic-pricing).

**How can I override pricing for some products if I'm using an automatic price list?**

Set exact prices for those products on the automatic list. This lets you automate your pricing and still set specific prices for some products.

- **For one product:** in the **Pricing > Price editor** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/editor)), or **SparkLayer Wholesale > Pricing > Price editor** in the Shopify app, open the variant and click **Override for this SKU** on the list's card. See [Override an automatic price for one SKU](https://docs.sparklayer.io/help/pricing/price-editor.md#override-an-automatic-price-for-one-sku).
- **For many products:** 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, click **Upload** next to your automatic price list and upload a CSV file with the prices you want to set. See [Upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md).

The list's **Type** then shows how many SKUs you've set, for example **Automatic + 12 SKU**.

**If I change a price in my store, how quickly do automatic price lists update?**

Straight away. Price changes in your platform update your automatic price lists instantly.

## Manual price lists

**How do I remove a product's price from a manual price list?**

| To remove | Do this |
| --- | --- |
| **Some prices for one product** | In the **Pricing > Price editor** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/editor)), or **SparkLayer Wholesale > Pricing > Price editor** in the Shopify app, search for the product, open the variant and click **Remove** next to the prices you want to delete. |
| **Prices for several SKUs** | Clear the price list (below), then upload a CSV file with only the prices you want to keep. A blank price in a CSV file doesn't remove a price. |
| **Every price for every product** | Open the **⋯** menu next to the price list, click **Clear**, then **Clear prices**. |

**How do I clear (empty) a manual price list?**

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, open the **⋯** menu next to the price list, click **Clear**, then **Clear prices**. This removes every SKU price uploaded to the list. On an automatic list, the automatic rule stays.

**How do I see prices I’ve already uploaded?**

- Download the price list as a CSV file: 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, open the **⋯** menu next to the price list and click **Download CSV**.
- Search for a product in the [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md) and open the variant to see its price on every list.
- Sign in to your store as a B2B customer and view the product page. See [Test as a B2B customer](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#test-as-a-b2b-customer) to make sure you're signed in correctly.

## Assigning prices to customers

**Can I assign several price lists to one customer group or customer?**

Yes. At **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app, click the group's name and find **Price lists** (click **+ Override** if it's under **Inherited rules**). Click **Add price list** to add another, then click **Save** in the save bar. See [Assign a price list to customers](https://docs.sparklayer.io/help/pricing/managing-pricing.md#assign-a-price-list-to-customers).

If a SKU is in more than one of the price lists, the first list it's in wins: see [Which price list wins](https://docs.sparklayer.io/help/pricing/managing-pricing.md#price-list-order). To give a single customer several price lists, see [Prices for one customer](https://docs.sparklayer.io/help/pricing/customer-pricing.md).

**Which price wins when a product is in several price lists?**

The first price list, in the order shown on the customer group, that contains the SKU. See [Which price list wins](https://docs.sparklayer.io/help/pricing/managing-pricing.md#price-list-order).

**How do I assign a price list to a specific customer?**

Add the price list's handle to the customer's price lists field (the `price_lists` metafield) on their record in your store admin. The customer then sees that price list instead of their customer group's. See [Give a customer their own price lists](https://docs.sparklayer.io/help/pricing/customer-pricing.md#give-a-customer-their-own-price-lists). To give a whole company its own prices, choose a **Price list** on the [company page](https://docs.sparklayer.io/help/customers/companies.md#prices-and-rules) instead.

## Quantity pricing

**How do I set up quantity (tiered) pricing?**

Add a `qty` column to your price list CSV, with a row for each price break. See [Quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md).

**Do I need a price for a single unit if I use quantity pricing?**

Yes. When you import a price list with tiered pricing, include a price for a single unit for every SKU. For example:

```csv
sku,price,qty
123-abc,14.99,1
123-abc,10.99,5
```

## Discounts

**How do I set up coupon codes for checkout?**

Create a discount and require a coupon code, for example a code that gives 10% off the order. Discounts need the Growth plan. See [Require a coupon code](https://docs.sparklayer.io/help/pricing/discounts.md#require-a-coupon-code).

**How do I discount a collection or product range?**

Add a rule to the discount: under **Rules**, click **New rule** and choose the products, collections or tags the cart must include. See [Restrict a discount to certain products](https://docs.sparklayer.io/help/pricing/discounts.md#restrict-a-discount-to-certain-products). For more off as the quantity goes up, use [volume tiers](https://docs.sparklayer.io/help/pricing/discounts.md#set-up-volume-tiers).

Without discounts, there's a workaround:

1. Create a new product in your catalogue with a variant for each product you want to include in the offer.
2. Set a [minimum product quantity](https://docs.sparklayer.io/help/storefront/quantity-rules.md), which makes the customer order at least a set number of the product (for example 3).
3. Use [quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md) to set the discounted rates (for example buy 3 and the price is 10% lower).
4. In Shopify, hide these products from retail customers by not adding them to a collection.

**How do I set up discounts based on an order total?**

Use order sub-total limits or order item limits, so a discount applies once the order total or the number of items reaches a threshold. See [Set minimum or maximum order requirements](https://docs.sparklayer.io/help/pricing/discounts.md#set-minimum-or-maximum-order-requirements).

## Diagnosing pricing issues

If prices still aren't right after the checks above, find where the price is missing. To check whether a product has prices on a price list:

1. Go to the **Pricing > Price editor** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/editor)), or **SparkLayer Wholesale > Pricing > Price editor** in the Shopify app and search for the product's name or SKU.
2. Open the variant.
3. Check its card for each price list. A manual list without a price for the SKU means customers on that list won't see a price from it.

To check that SparkLayer has the product at all, use **Product data lookup** at **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app. See [Product and customer sync](https://docs.sparklayer.io/help/integrations/data-sync.md).

If you're using the [SparkLayer API](https://docs.sparklayer.io/developers/api.md), your developer can also check the price data there.

For other common problems, see [Troubleshooting](https://docs.sparklayer.io/help/troubleshooting.md).


---

# Customers and companies

URL: https://docs.sparklayer.io/help/customers

How companies, their locations, the people who buy for them and customer groups fit together in SparkLayer, and where to manage each one in the app.

> **Quick summary**
>
> - The 
>   **Companies**
>    area is where you manage who buys from you and on what terms. Open it at 
>   **Companies** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/companies)), or **SparkLayer Wholesale > Companies** in the Shopify app
>   . It has three screens: 
>   **Companies**
>   , 
>   **Customers**
>    and customer groups.
> - A **company** is a business you sell to. It can be split into **locations**, such as stores or regions. A **customer** is a person who signs in to your store and orders, on their own or for a company.
> - A **customer group** sets prices (through its price lists), payment methods and order rules. Every B2B customer is in one. The **Base customer group** covers everyone else.
> - On Shopify, companies and locations are your Shopify B2B companies, kept in sync both ways. Customers and customer groups work on every platform.## How it fits togetherSparkLayer uses four building blocks:

- **Company**: a business you sell to, such as a shop chain or a distributor. You give it a customer group, an optional price list, pay later and the sales agents who look after it.
- **Location**: part of a company, such as a store, a region or a warehouse. Locations can sit inside each other. Each one uses the settings of the level above unless you change them.
- **Customer**: a person who signs in to your store and orders. A customer can belong to a company and be added to some of its locations.
- **Customer group**: the rules a set of customers buy on: their price lists, payment methods and order limits.A company holds locations, and people are added to the locations they order for:Who belongs to what:

1. **Company**: The business. It's in a customer group, and can have its own price list and pay later setting
2. **Locations**: Stores or regions inside the company. Each uses the company's settings unless it sets its own
3. **People**: The customers who order. Each person is added to the locations they order for, as a Buyer, Approver or ManagerA customer doesn't have to belong to a company. Someone who buys for themselves, or a store that doesn't use companies, gets their customer group's settings.## Where a buyer's prices come fromA buyer's prices come from a customer group and its price lists:Where a buyer's prices come from:

1. **Customer group**: The customer's group, or their company's group if they're in a company
2. **Price list**: The group's price lists, unless the company, the location or the customer has a price list of its own
3. **Buyer signs in**: They see those prices, the group's payment methods and its order rules## What overrides whatEach setting starts broad, and you can replace it with a more specific one. The most specific setting wins.| What                                 | Starts from                                                                                                                                                 | Replaced by                                                                                                                                                                                                                      |
| --- | --- | --- |
| **Prices** | The [customer group's price lists](https://docs.sparklayer.io/help/customers/customer-groups.md#assign-price-lists). | A **Price list** on the [company](https://docs.sparklayer.io/help/customers/companies.md#prices-and-rules), then on a [location](https://docs.sparklayer.io/help/customers/company-locations.md#prices-and-rules). For one person, use [customer pricing](https://docs.sparklayer.io/help/pricing/customer-pricing.md). |
| **Payment methods and order rules** | The [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md#what-a-customer-group-controls). Each group follows the Base customer group until you override a rule. | A different **Customer group** on the company, or on a location. |
| **Pay later** | The [company](https://docs.sparklayer.io/help/customers/companies.md#paying). | One of its [locations](https://docs.sparklayer.io/help/customers/company-locations.md#paying). |
| **Sales agents who look after them** | The company. | One of its locations. |
| **Who orders for a business**        | Never inherited.                                                                                                                                            | Each person is added to the exact [locations](https://docs.sparklayer.io/help/customers/company-locations.md#people-and-location-roles) they order for, as a **Buyer**, **Approver** or **Manager**.                                                          |Which sales agents can order for a customer is also set on the sales agent's page, where you tick the [customer groups they can see](https://docs.sparklayer.io/help/sales-reps.md#restrict-which-customers-a-sales-agent-can-see).### How a buyer's price is chosenSparkLayer uses the most specific price list that applies, in this order:1) **The customer's own price lists**, set with [customer pricing](https://docs.sparklayer.io/help/pricing/customer-pricing.md).
2) **Their location's price list**
   , if it or a location above it has one. It applies to that location and the locations inside it.
3) **Their company's price list**
   , if it has one. It applies to everyone at the company.
4) **Their customer group's price lists.** That's the company's customer group if it has one, otherwise the group from the customer's own tag. A group without price lists uses the Base customer group's. If a product is in several of the group's lists, the first list it's in wins.With no price list at any level, the buyer sees your standard prices.Rules, such as payment methods and order limits, follow the same order: the location's customer group, then the company's customer group, then the group from the customer's own tag.## Where to find itThe two versions of the app have the same screens:* **SparkLayer Dashboard**: the **Companies** group in the sidebar, with **Companies**, **Customers** and **Groups**.
* **Shopify app** (**SparkLayer Wholesale** in Shopify admin): **Companies**, with the tabs **Companies**, **Customers** and **Customer groups**.| To do this                                                                                | Go to                                                                                                                                                                                                                                                |
| --- | --- |
| See the businesses you sell to, and set their pricing, pay later, people and sales agents | **Companies** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/companies)), or **SparkLayer Wholesale > Companies** in the Shopify app |
| Split a company into locations and choose who orders for each | **Companies > Manage locations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/companies)), or **SparkLayer Wholesale > Companies > Manage locations** in the Shopify app |
| Find a customer, invite a buyer and check customer sync errors | **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app |
| Set price lists, payment methods and order rules for groups of customers | **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app |
| Make a customer a sales agent and choose who they look after | **Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app |
| Turn company users and company locations on or off | **Settings > Configurations > Ordering** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Ordering** in the Shopify app |
| Turn on messages on orders and quotes                                                     | **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app |## Get your first buyer ordering1) [Create a price list](https://docs.sparklayer.io/help/pricing/managing-pricing.md#create-a-price-list) 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.
2) [Give it to a customer group](https://docs.sparklayer.io/help/customers/customer-groups.md#assign-price-lists) at **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 a [new group](https://docs.sparklayer.io/help/customers/customer-groups.md#create-a-customer-group) with its own prices.
3) [Add a buyer to the group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md) in your platform (on Shopify, with a tag), or [invite a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md) from **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app and choose their customer group. On Shopify, buyers can also [apply for a trade account](https://docs.sparklayer.io/help/guides/approve-trade-applications.md) with a SparkLayer form, for you to approve into a group.
4) [Place a test order](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order) as a buyer to check their prices and checkout.**More detail**

- [Setup](https://docs.sparklayer.io/help/get-started.md) walks you through the same steps, and ticks each one off as you go. For the same steps as one guide, see [Set up wholesale prices for your trade customers](https://docs.sparklayer.io/help/guides/set-up-wholesale-prices.md).
- Already have trade customers in Shopify? See [Move your existing wholesale customers onto SparkLayer](https://docs.sparklayer.io/help/guides/move-existing-customers.md).
- To give a business its own terms, 
  [create a company](https://docs.sparklayer.io/help/customers/companies.md#create-a-company)
   and choose its customer group and price list.## Key terms| Term                                                                         | Meaning                                                                                         |
| --- | --- |
| [B2B customer](https://docs.sparklayer.io/help/glossary.md#b2b-customer) | A customer who sees your B2B prices and ordering rules when they sign in. |
| [Company](https://docs.sparklayer.io/help/customers/companies.md) | A business you sell to. On Shopify, a Shopify B2B company. |
| [Company location](https://docs.sparklayer.io/help/customers/company-locations.md) | A store, region or site of a company. Locations nest, and inherit from the level above. |
| [Location role](https://docs.sparklayer.io/help/customers/company-locations.md#people-and-location-roles) | What a person can do at a location: **Buyer**, **Approver** or **Manager**. |
| [Customer group](https://docs.sparklayer.io/help/customers/customer-groups.md) | The rules shared by a set of B2B customers. Every store has a **Base customer group**. |
| [Company user](https://docs.sparklayer.io/help/customers/company-users.md) | A colleague a customer invites to share their account, with a **Standard** or **Limited** role. |
| [Sales agent](https://docs.sparklayer.io/help/sales-reps.md)                                              | A member of your team who orders on behalf of customers.                                        |## In this section- [Companies](https://docs.sparklayer.io/help/customers/companies.md): The businesses you sell to: their pricing, pay later, people and sales agents
- [Company locations](https://docs.sparklayer.io/help/customers/company-locations.md): Split a company into stores or regions, and choose who orders for each
- [Find and manage customers](https://docs.sparklayer.io/help/customers/managing-customers.md): Find a customer, check what they'll see and fix sync errors
- [Invite a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md): Send a buyer an invite to create their trade account
- [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md): Set price lists, payment methods and order rules for groups of customers
- [Add customers to a group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md): Tag customers into the right group, check they've synced and test as one
- [Company users](https://docs.sparklayer.io/help/customers/company-users.md): Let customers invite colleagues and approve each other's orders
- [Customise My Account](https://docs.sparklayer.io/help/customers/account-and-addresses.md): Customise the My Account area, addresses, order statuses and redirects
- [Order timeline and messages](https://docs.sparklayer.io/help/customers/timeline.md): Message customers and keep internal notes on orders and quotes


---

# Companies

URL: https://docs.sparklayer.io/help/customers/companies
Applies to: Shopify

See the businesses you sell to and set each company's customer group, price list, pay later, people and sales agents, synced with your Shopify B2B companies.

> **Companies are in early access.** Request it for your store. [Request early access](mailto:product@sparklayer.io?subject=Early%20access%20to%20Companies).

> **Quick summary**
>
> - A company is a business you sell to. Set its terms once, and everyone who buys for it orders on them. Find your companies at **Companies** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/companies)), or **SparkLayer Wholesale > Companies** in the Shopify app. Companies are on every plan.
> - Companies are your Shopify B2B companies and locations, kept in sync both ways. Shopify holds who they are. SparkLayer adds what they buy at: customer group, price list, payment terms, sales agents and ordering rules.
> - On a company's page, you set its **Customer group**, an optional **Price list**, **Let them pay later**, its **Main contact** and **Admins**, the **Sales agents who look after them** and its **IDs in other systems**.
> - Big companies can be split into [locations](https://docs.sparklayer.io/help/customers/company-locations.md), such as stores or regions. Each location uses the company's settings unless you change them.

## How it works

A company groups the people who buy for the same business. Everyone at the company orders at its prices and payment terms. The sales agents you choose can order for them.

The company itself lives in Shopify B2B, at **Customers > Companies** ([open in the Shopify admin](https://admin.shopify.com/companies)). SparkLayer reads your companies, their locations and their contacts, and stores its own settings against each one.

| Kept in | What it holds |
| --- | --- |
| **Shopify B2B** | Who they are: the company's name, its locations and their addresses, and its contacts (the people who buy). |
| **SparkLayer** | What they buy at: the customer group (so the prices, payment methods and order rules), an optional price list for the company or a location, whether they can pay later and what they owe, the sales agents who look after them, and each person's role at a location. |

From Shopify company to B2B ordering:

1. **Company in Shopify B2B**: Created in Shopify, or with Create company in SparkLayer
2. **Kept in sync**: Changes in either place reach the other
3. **Terms set in SparkLayer**: Customer group, price list, pay later and sales agents
4. **People order**: Everyone at the company buys on those terms

Everyone at a company still needs the `b2b` tag on their Shopify customer record, as other B2B customers do. See [Add B2B customers on Shopify](https://docs.sparklayer.io/help/platforms/shopify/invite-customers.md).

On other platforms, manage your B2B customers with [customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md) and [company users](https://docs.sparklayer.io/help/customers/company-users.md). Companies is only available on Shopify.

## Create a company

1. Go to **Companies** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/companies)), or **SparkLayer Wholesale > Companies** in the Shopify app and click **Create company**.
2. Under **Company**, enter the **Company name**, for example `Northwind Toys`.
3. Under **Prices and rules**, choose its **Customer group**. Leave **Price list** as **Use the customer group's price list** unless the company needs different prices.
4. Under **Paying**, turn on **Let them pay later** if they can order now and pay by invoice.
5. Under **Sales agents**, choose the **Sales agents who look after them**, or leave **Any sales agent**.
6. Click **Save** in the bar at the top of the page. You'll see "Company created".

If you didn't enter a name, you'll see "Give the company a name" instead.

Then finish setting up the company:

1. Add its people: [invite them as buyers](https://docs.sparklayer.io/help/customers/invite-buyers.md) and choose the company, or add them as contacts of the company in Shopify.
2. Open the company again and choose its **Main contact** and **Admins** under [People](#people).
3. If it orders for several stores or regions, [split it into locations](https://docs.sparklayer.io/help/customers/company-locations.md#add-a-location). Then [add each person to the locations they order for](https://docs.sparklayer.io/help/customers/company-locations.md#add-people-to-a-location).

**More detail**

- Because companies sync both ways, the new company is added to your Shopify B2B companies too. 
- Until you add its people, the company's **People** card says "After you create the company, add its people from Customers."
- **IDs in other systems** is optional. Fill it in only if an accounting system, ERP or other tool needs to match the company.

## Edit a company

1. At **Companies** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/companies)), or **SparkLayer Wholesale > Companies** in the Shopify app, click the company's name, or click **⋯** and then **Edit company**.
2. Change what you need. See [The company page](#the-company-page) for every field.
3. Click **Save** in the bar at the top. You'll see "Company saved". To undo your changes instead, click **Discard**.

## The Companies screen

The Companies screen lists every company, with its pricing and whether it can pay later. Go to **Companies** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/companies)), or **SparkLayer Wholesale > Companies** in the Shopify app, or click the **Companies** figure ("Businesses you sell to") on Home.

| Part | What it shows / does |
| --- | --- |
| **Open in Shopify** | Opens **Customers > Companies** in your Shopify admin. |
| **Create company** | Opens the form for a new company. See [Create a company](#create-a-company). |
| Search | Type part of a company's name (**Search companies**). The list filters as you type. |
| **Company** | The company's name, with how many people and locations it has underneath, for example "4 people · 11 locations". Click the name to open the company. |
| **Pricing** | The company's own price list. Without one, the customer group's pricing, for example "Trade pricing". Without either, **Standard pricing**. |
| **Pay later** | "Owes" and the amount, **On, nothing owed**, or **Off**. |
| **⋯** | **Edit company** opens the company. **Manage locations** opens its [locations](https://docs.sparklayer.io/help/customers/company-locations.md). |
| **Works with Shopify B2B** | A reminder of what Shopify holds and what SparkLayer adds, with **Open Companies in Shopify**. |

If you have no companies yet, the list says **No companies yet** ("Add the businesses you sell to."), with **Create company**. If your search finds nothing, it says **No companies found** ("Try a different name.").

## The company page

The company page holds everything SparkLayer stores about a company, in these cards.

### Company

| Field | What it's for |
| --- | --- |
| **Company name** | The business's name, for example "Northwind Toys". |

### Prices and rules

| Field | Options | What it does |
| --- | --- | --- |
| **Customer group** | **Base customer group** (the default), or any of your groups | "Sets their prices, payment methods and order rules." See [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md). |
| **Price list** | **Use the customer group's price list** (the default), or any of your price lists | "Only set this if this company needs different prices from its group." |

### Paying

| Field | What it does |
| --- | --- |
| **Let them pay later** | A switch. When it's on, "They order now and pay by invoice, up to their credit limit." |
| **Currently owes** | Shown under the switch when the company has an unpaid balance, for example "Currently owes $1,240.50." |

The credit limit isn't set on the company page. A customer's credit limit, net terms and balance show on their [customer page](https://docs.sparklayer.io/help/customers/managing-customers.md#a-customers-page), under **Financial details**. See [Credit limits and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md). 

### People

The people at a company are the customers whose **Company** is this company.

| Field | What it does |
| --- | --- |
| **Main contact** | The one person who "Gets order and invoice emails for the company." Each person shows as their name and email. |
| **Admins** | Tick the people who manage the company. "Admins can invite people and manage locations for their company." |

If no one is in the company yet, the card says "No one is in this company yet. Add people from Customers."

### Sales agents

| Field | Options | What it does |
| --- | --- | --- |
| **Sales agents who look after them** | **Any sales agent** (the default), or a group of sales agents, such as **UK reps** | "These sales agents can see them and order on their behalf." |

See [Sales agents](https://docs.sparklayer.io/help/sales-reps.md) for what agents can do.

### Locations

This card only shows on an existing company. It says how many locations the company has and names the top-level ones, for example "11 locations: UK, USA, Australia and more inside them." Click **Manage locations** to open them.

With no locations, it says "Split this company into stores or regions if they need different prices or people.", with **Add a location**. See [Company locations](https://docs.sparklayer.io/help/customers/company-locations.md).

### IDs in other systems

"Optional. Only needed if you sync with an accounting system, ERP or other tool."

| Field | What it's for |
| --- | --- |
| **Accounting system ID** | The company's ID in your accounting system. |
| **Shopify company ID** | The company's ID in Shopify B2B. |
| **Other system ID** | The company's ID in an ERP or any other tool. |

## How a company's settings reach its locations

A company's **Customer group**, **Price list**, **Pay later** and **Sales agents** are the starting point for all its locations. Each location shows **Same as** and the level above it until you change it. So:

- To change something for the whole company, change it on the company page.
- To change it for one store or region, change it on that [location](https://docs.sparklayer.io/help/customers/company-locations.md#the-location-page). The locations inside it follow.

## Delete a company

1. Open the company.
2. Click **More actions**, then **Delete company**.
3. Click **Delete company** to confirm.

The company's locations are deleted too. Its people stay as customers, but lose the company's prices and payment terms. This can't be undone. 

## FAQs

**Do I have to use companies?**

No. A customer who isn't in a company buys at their [customer group's](https://docs.sparklayer.io/help/customers/customer-groups.md) settings. Use companies when several people buy for the same business, or when one business needs its own prices, payment terms or locations.

**Can I change a company in Shopify instead?**

Yes. Companies are kept in sync both ways, so a company, location or contact you add or change in Shopify B2B shows in SparkLayer too. Prices, payment terms and sales agents are set in SparkLayer.

**Why does a company show Standard pricing?**

Neither the company nor its customer group has a price list, so it sees your standard prices. Give the company a **Price list**, or give its customer group one. See [Assign price lists](https://docs.sparklayer.io/help/customers/customer-groups.md#assign-price-lists).

**Does SparkLayer use Shopify catalogs or payment terms?**

No. Prices come from SparkLayer's price lists, and payment methods and order rules from its customer groups. See [Shopify Companies](https://docs.sparklayer.io/help/platforms/shopify/companies.md).

**How do I add someone to a company?**

[Invite them as a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md) and choose the company, or add them as a contact of the company in Shopify. Then add them to the [locations](https://docs.sparklayer.io/help/customers/company-locations.md#add-people-to-a-location) they order for.

**What happens to the people when I delete a company?**

They stay as customers, but they lose the company's prices and payment terms and go back to their own customer group's settings.


---

# Company locations

URL: https://docs.sparklayer.io/help/customers/company-locations

Split a B2B company into stores, branches or regions with their own prices, pay later and people, and let buyers order for one location at a time.

> **Companies are in early access.** Request it for your store. [Request early access](mailto:product@sparklayer.io?subject=Early%20access%20to%20Companies).

> **Quick summary**
>
> - A company can be split into **locations**, such as stores, branches or regions. Locations can sit inside each other as deep as you need, for example UK > North > Leeds. Company locations are on every plan.
> - Each location uses the settings of the level above (another location, or the company) unless you change them. That covers its customer group, price list, pay later and sales agents.
> - Set them up at **Companies > Manage locations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/companies)), or **SparkLayer Wholesale > Companies > Manage locations** in the Shopify app. Add people to each location and give each one a role: **Buyer**, **Approver** or **Manager**.
> - On your store, someone at the company orders for **one location at a time**, with that location's prices, payment options and address. **Company locations** is on by default; turn it off at **Settings > Configurations > Ordering** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Ordering** in the Shopify app.

## How it works

A company that buys from you often orders for several places: a chain of shops, regional branches, or a head office and its warehouses. Each place can need its own prices, payment terms and people. With company locations, the person ordering picks the place first. The cart, checkout and My Account then follow it.

This page has two halves: [setting up locations](#set-up-a-companys-locations) in the app, and [how buyers order for a location](#how-buyers-order-for-a-location) on your store.

### How locations share settings

Locations form a tree, with the company at the top. There's no separate "region" type: a region is a location with other locations inside it.

Each location **inherits from the level above unless it sets its own**. For example, every store in the North region uses the region's price list until you give one store a different list. When you change a setting on the company, every location that hasn't set its own follows.

How settings pass down the tree:

1. **Company**: Northwind Toys: Trade customer group, pay later on
2. **Region**: North: Same as Northwind Toys
3. **Store**: Leeds: its own price list, everything else the same as North

| Setting | How it works |
| --- | --- |
| **Customer group**, **Price list**, **Pay later** and **Sales agents** | Set on the [company](https://docs.sparklayer.io/help/customers/companies.md#edit-a-company), and changed on any location that needs its own. Each location shows **Same as** and the level above until you change it. |
| **People** | Never inherited. Each person is added to the exact locations they order for. |
| **Address** | Never shared. Each location ships to its own address. On Shopify, that's the address of its Shopify company location. |
| **Balance** | Rolls up the tree. A region owes what its stores owe, shown in the **Owes** column. |
| **Credit limit** | Belongs to the company. There's one limit, shared by every location, and the credit available is that limit minus what the whole company owes. |

On Shopify, companies and their locations are your [Shopify B2B companies](https://docs.sparklayer.io/help/platforms/shopify/companies.md), kept in sync both ways. 

## Set up a company's locations

1. Check **Company locations** is on (it is by default): see [Turn company locations on or off](#turn-company-locations-on-or-off).
2. At **Companies** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/companies)), or **SparkLayer Wholesale > Companies** in the Shopify app, click **⋯** next to the company, then **Manage locations**.
3. [Add a location](#add-a-location) for each region or store. Add regions first, then the stores inside them.
4. On each [location page](#the-location-page), change only what's different from the level above, such as its **Price list**.
5. [Add people to each location](#add-people-to-a-location) and choose their role.

## Turn company locations on or off

1. Go to **Settings > Configurations > Ordering** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Ordering** in the Shopify app.
2. Turn **Company locations** on or off ("Customers in a company choose which location they're buying for, and get that location's pricing."). It's on by default.
3. Click **Save** in the bar at the top of the page.

## The locations screen

The locations screen shows a company's location tree, with each location's pricing, people and balance. Open it in either of these ways:

- At **Companies** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/companies)), or **SparkLayer Wholesale > Companies** in the Shopify app, click **⋯** next to the company, then **Manage locations**.
- On the company's page, under **Locations**, click **Manage locations** (or **Add a location** if it has none).

The screen is named after the company, for example "Museum of Play Group locations". Above the list: "Each location uses the company's settings unless you change them. Put locations inside others to group them, like stores inside a region."

| Column | What it shows |
| --- | --- |
| **Location** | The location's name, indented under the location it sits in. Click it to open the location. |
| **Pricing** | The location's own price list, its customer group's pricing (for example "Trade pricing"), or **Same as** and the level above. |
| **People** | How many people are in the location, or **No one yet**. |
| **Owes** | The location's unpaid balance, or **Nothing**. |
| **⋯** | **Edit location**, **Add a location inside** and the location's name, and **Delete**. |

A company with no locations shows **No locations yet**: "Split this company into stores or regions if they need different prices or people. Each location uses the company's settings unless you change them."

## Add a location

1. On the locations screen, click **Add a location** to add one at the top level. To add one inside another location, click **⋯** next to it and choose **Add a location inside** and its name.
2. Enter a **Location name**, for example `Glasgow store`. The help text says which settings it starts with, for example "It uses Museum of Play Group's settings until you change them."
3. Click **Add location**. You'll see "Location added".

You can also add a location inside the one you're editing: on the location page, click **More actions**, then **Add a location inside**.

## The location page

The location page holds one location's settings. To open it, click the location's name, or click **⋯** and then **Edit location**. Change what you need, then click **Save** in the bar at the top. You'll see "Location saved", and you go back to the locations screen.

### Location

| Field | What it does |
| --- | --- |
| **Location name** | The location's name. |
| **Sits under** | Where it sits in the tree: the company (top level), or another location. Moving it "brings the locations inside it too". You can't move a location inside itself or one of its own locations. |

### Prices and rules

| Field | Options | What it does |
| --- | --- | --- |
| **Customer group** | **Same as** the level above, or any of your groups | "Sets their prices, payment methods and order rules." |
| **Price list** | **Same as** the level above, or any of your price lists | Leave it as **Same as** unless this location needs its own prices. |

### Paying

| Field | Options | What it does |
| --- | --- | --- |
| **Pay later** | **Same as** the level above, **On** or **Off** | "Order now and pay by invoice, up to their credit limit." With an unpaid balance, the card also says what the location currently owes. |

### People

Who can order for this location, and their role. See [People and location roles](#people-and-location-roles).

### Sales agents

| Field | Options | What it does |
| --- | --- | --- |
| **Sales agents who look after them** | **Same as** the level above, or a group of sales agents, such as **UK reps** | "These sales agents can see them and order on their behalf." |

### IDs in other systems

The same optional fields as a company: **Accounting system ID**, **Shopify company ID** and **Other system ID**.

## People and location roles

Location roles decide who can order for each location. A person joins the company first, then you add them to the locations they order for:

1. **They join the company.** A person belongs to a company through the **Company** on their customer record. That happens when you [invite them as a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md) and choose the company, or when they're a contact of the company in Shopify and sync across.
2. **You add them to locations.** On each location page, add them under **People** and choose their role.

One person can be in several locations, for example a buyer who orders for both Leeds and Manchester.

| Role | What they can do |
| --- | --- |
| **Buyer** | "Places orders for this location." The default for anyone you add. |
| **Approver** | "Checks and approves orders before they're placed." |
| **Manager** | "Everything a buyer can do, plus managing this location's people." |

### Add people to a location

1. Open the location page.
2. Under **People**, choose someone from **Add someone from** and the company's name. The list shows the company's people who aren't in this location yet.
3. Click **Add**. This saves straight away ("Added to the location").
4. In the **Role** column, choose **Buyer**, **Approver** or **Manager**, then click **Save** in the bar at the top.

The list shows each person's name and email, and their role. With nobody added, it says "No one is in this location yet."

If someone isn't in the **Add someone from** list, they're not in the company yet: [invite them](https://docs.sparklayer.io/help/customers/invite-buyers.md) and choose the company first.

### Remove someone from a location

1. Under **People**, click **Remove** next to the person.
2. Click **Remove** to confirm.

"They stay in the company, just not in this location."

## Move or delete a location

To move a location, open it, change **Sits under**, then click **Save**. The locations inside it move too.

To delete a location:

1. Click **⋯** next to the location and choose **Delete**. Or open the location and click **More actions**, then **Delete location**.
2. Click **Delete location** to confirm.

The locations inside it are deleted too. Its people stay in the company. This can't be undone.

## How buyers order for a location

The rest of this page is about your store: what someone at the company sees when they sign in, and how they switch between locations.

Ordering for a company location:

1. **Sign in**: The person signs in for the company, or a sales agent orders for it
2. **Choose a location**: The location chip shows the current location; click it to switch
3. **Prices and payment follow**: The cart uses the location's price list and payment options
4. **Check out**: The order goes to the location's address and is recorded against it

### The location chip

The location chip shows which location someone is ordering for. On your store, it sits in the widget's top bar, to the left of the avatar.

| What it shows | When |
| --- | --- |
| A pin and the location's name | The person is ordering for that location. |
| Up and down arrows beside the name | There's more than one location to choose from. |
| The pin on its own | A sales agent's top bar is full. The location's name is in the chip's tooltip. |
| **No location** | The person hasn't been added to any location yet. |
| No chip | The company has no locations. |

### Choose a location

1. Click the location chip in the top bar.
2. In **Choose a location**, click the location to order for.

The cart, checkout and My Account switch to that location straight away. A notification confirms it, for example **Ordering for** and the location's name. Underneath, it shows the location's price list and whether it can pay later (or what it owes).

**More detail**

- **Current location** comes first, with its place in the tree (for example a region, then the store), so it's never lost at the bottom of a long list.
- **Recent**, for companies with more than six locations, lists the last three locations the person ordered for.
- Everything else follows, grouped under the region it's in. Someone who can only reach some locations sees **Your other locations**, and a company with no regions shows **Other locations**.
- Each row shows the location's name, its address and, on the right, its price list as a short badge such as **30% off** (hover to see the list's name). **Pay later off** marks a location that can't pay on account or by invoice.
- With more than six locations, a **Find a location** search appears. Every word typed must match the location's name or a place above it, so a region's name plus a store's name finds that store. Press Enter to choose the first match.
- Use the arrow keys to move through the list, and Escape, the backdrop or **×** to close it.

If the person can only order for one location, the box says so, and says a company admin can add them to more. If they're in no location, it names the company admin to ask.

### What changes with the location

| Where | What changes |
| --- | --- |
| [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) | Each line's unit price comes from the location's price list. For example, on a list that's 30% off RRP, a product with an RRP of $100.00 costs $70.00. The crossed-out sub-total is the RRP total. A price a sales agent changed by hand on a line keeps the agent's price. |
| Checkout: **Details** | The **Shipping Address** is the location's own, with a note saying it's delivering to that location's address and a **Change location** link. |
| Checkout: **Review & Pay** | With **Pay later off**, the pay-later methods (such as **Pay on Account** and **Pay by Invoice**) are hidden and card payment is selected. The **Order Summary** has an **Ordering for** row naming the location, with **Change**. |
| Checkout: **Complete** | The confirmation message names the location the order was placed for. The confirmation goes to the email address of the person who placed the order, not the company's. |
| My Account: greeting and **My Details** | The signed-in person's own first name, name and email address, not the company's. |
| My Account: **Recent Activity** | The location's orders, each naming the location it was placed for. A region also shows its stores' orders. A location with no orders says so, with **Change location**. |
| My Account: **Financials** | The payment terms, the location's unpaid balance and the company's credit limit, with a note of how much of the shared limit is left. |
| My Account: **Address Book** | The location's address, as the default shipping and billing address, with **Change location**. |
| My Account: **Company Users** | The company's people, each with the locations they can reach (or "No location yet"), their role (**Admin** or **Standard**) and **(you)** beside the signed-in person. |
| Account menu | Under the company's name, the person's name and their location. A sales agent's menu doesn't change. |

See [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md), [Cart and checkout](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md) and [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) for the rest of each screen.

### Who can order for which locations

Someone can order only for the locations they've been added to. Where those locations sit in the tree doesn't matter: being added to one store doesn't give someone its region, or the other stores in it.

| Who | Locations they can choose | What else they can do |
| --- | --- | --- |
| Company admin (one of the company's **Admins**) | Every location | Manage the company's people and locations: **Add new address**, **Invite new user** and the actions on **Company Users**. |
| Anyone else at the company | Only the locations they've been added to | Order for those locations. They don't see **Add new address** (in My Account or at checkout), **Invite new user** or the **Company Users** actions. |
| [Sales agent](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md) | Every location of the company they're ordering for | Order for any location, and manage people and locations like an admin. |

To give someone more locations, [add them on the location page](#add-people-to-a-location). A company admin, or a sales agent who looks after the company, can do it too. 

## FAQs

**Why can't someone see a location?**

They haven't been added to it. People only see the locations they've been added to, even if they're in another store in the same region. Company admins and sales agents see every location. To fix it, add them on the location page under **People**.

**Why isn't someone in the Add someone list?**

They're not in the company yet. A person joins a company through the **Company** on their customer record: [invite them as a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md) and choose the company, or add them as a contact of the company in Shopify.

**How do I create a region?**

Add a location with the region's name, such as `North`. Then add the stores inside it with **Add a location inside**. A region is a location with other locations inside it.

**Does each location have its own credit limit?**

No. The credit limit belongs to the company and is shared by every location. **Financials** shows the current location's unpaid balance and how much of the company's limit is left.

**Why can't a customer pay on account or by invoice?**

The location they're ordering for has **Pay later** off, so only card payment is available. Check the setting on the location, the locations above it and the company. A location uses the nearest setting above it unless it has its own.

**Why don't the prices match the customer group's price list?**

With company locations, the cart uses the price list of the location being ordered for. Check which location the location chip shows. Then check which price list that location uses, or the location or company above it.

**Can someone change the delivery address at checkout?**

The checkout uses the location's own address. To deliver somewhere else, choose a different location with **Change location**. Company admins can also add addresses.

**What happens to people when I delete a location?**

They stay in the company, just not in that location or the locations inside it. Add them to another location if they still need to order.


---

# Invite a buyer

URL: https://docs.sparklayer.io/help/customers/invite-buyers

Invite a buyer from SparkLayer: they get an email to create their trade account, join the customer group you choose and see your trade prices when they sign in.

> **Quick summary**
>
> - **Invite a buyer** adds a person to your store as a B2B customer in the customer group you choose, and emails them an invite. They see your trade prices as soon as they sign in.
> - Click **Invite buyer** at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app. You can also open it from Setup, Home and customer groups.
> - In the Shopify app, Shopify sends the invite and you can add the buyer to one of your Shopify B2B companies. In the SparkLayer Dashboard, SparkLayer sends its own branded invite.
> - **Copy registration link** gives you a link to your trade registration form instead, so buyers can apply themselves. You can still add customers by [tagging them in Shopify](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group).

## How it works

Inviting a buyer does the setup for you. SparkLayer adds them to Shopify as a customer with the customer group's tag (such as `b2b-trade`), so they're a B2B customer in that group straight away. It then emails them to create their account.

From invite to first order:

1. **You invite them**: Enter their email and choose their customer group
2. **They're added**: They're added to Shopify with the group's tag, and show as Invited in Customers
3. **They get an email**: It asks them to create their trade account
4. **They sign in**: They see your trade prices and can order any time

## Invite a buyer

Invite a buyer from **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app, or from any of the places in [Where to invite from](#where-to-invite-from). The box is slightly different in each version of the app.

**Shopify app:**

1. Click **Invite buyer** (or **Invite a buyer**).
2. Enter their **First name** and **Last name**, and their **Email**. Email is required.
3. Under **Company**, choose one of your Shopify B2B companies, or leave **No company**.
4. Under **Customer group**, choose their group. Each option shows the group and its price list, for example **Trade · Trade 20%**.
5. Click **Send invite**.

| Field | What it does |
| --- | --- |
| **First name**, **Last name** | Their name on the Shopify customer. |
| **Email** | Required. The address they sign in with. |
| **Company** | "Adds them as a contact at this Shopify B2B company." See [Companies](https://docs.sparklayer.io/help/customers/companies.md). |
| **Customer group** | "Adds the group's tag, like b2b-trade". The group sets their prices, payment methods and order rules. |

**What the buyer receives:** "Shopify emails them an invite to your store. They sign in with a one-time code, no password, and see trade prices straight away." Click **Edit the email in Shopify** to change it at **Settings > Notifications** ([open in the Shopify admin](https://admin.shopify.com/settings/notifications)).

**More detail**

- Without a company, Shopify sends its customer account invite.
- With a company, Shopify sends its B2B access email for company contacts.

**SparkLayer Dashboard:**

1. Click **Invite buyer** (or **Invite a buyer**).
2. Enter their **Email** (required), for example `buyer@theirshop.com`, and their **Name**, for example `Priya Shah`.
3. Optionally, type their company under **Company (optional)**, for example `Northwind Toys`.
4. Under **Customer group**, choose their group.
5. Click **Send invite**.

| Field | What it does |
| --- | --- |
| **Email** | Required. The address they sign in with. |
| **Name** | Their name. |
| **Company (optional)** | The business they buy for. |
| **Customer group** | The group sets their prices, payment methods and order rules. |

**What the buyer receives:** a SparkLayer email in your store's name. The **What they'll get** box shows a preview: your store's name and "invited you to order wholesale", then "Create your trade account to see your prices and order any time.", with a **Create trade account** button.

"They're added to Shopify with the group's tag, so SparkLayer shows them trade prices as soon as they log in."

You'll see "Invite sent to" and their email. The buyer appears at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app with **Access** set to **Invited** until they create their account.

If something's wrong, you'll see one of these instead:

| Message | What it means |
| --- | --- |
| Enter the buyer's email address | The email is missing or isn't a valid address. |
| That buyer already has an account | Someone with that email is already a customer. Find them at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app. To move them to another group, see [Assign customers to a customer group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group). |

Your first invite also completes the Setup step **Invite your first buyer**.

## Where to invite from

The same **Invite a buyer** box opens from each of these places:

| Where | What to click |
| --- | --- |
| **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app | **Invite buyer**, at the top of the page. |
| **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app | Step 3, **Invite your first buyer**: **Invite a buyer**. |
| **Home** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale** in the Shopify app | The getting-started card on Home lists the same steps as Setup, including **Invite a buyer**. |
| **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app | Under **Common tasks**, **Add a buyer to a group** ("Invite them straight into the group you choose"). |
| A customer group's page | **More actions**, then **Invite a buyer**. |

## Share your registration link

To let buyers apply themselves, share the link to your trade registration form:

1. In the **Invite a buyer** box, click **Copy registration link**. You'll see "Registration link copied".
2. Share the link by email, or put it on your website.

Applications arrive as entries on the registration form in [Forms](https://docs.sparklayer.io/help/forms.md). There, you approve or reject each one and choose the customer group. Approving one adds the buyer the same way as an invite, and also completes the Setup step. Forms are in the SparkLayer Dashboard only. 

## Other ways to add a buyer

| Way | When to use it |
| --- | --- |
| [Tag the customer in Shopify](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group) | For customers who already have an account on your store, or to add many at once. Give them `b2b`, plus the group's tag. |
| [Add them as a contact of a Shopify B2B company](https://docs.sparklayer.io/help/customers/companies.md) | For people at a company you already have. They sync to SparkLayer as people at that company. |
| [Approve a registration form entry](https://docs.sparklayer.io/help/forms/entries.md) | For buyers who applied through your trade registration form. |

On other platforms, add B2B customers in your platform's admin: see [Assign customers to a customer group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group). Invite a buyer is only available on Shopify.

## FAQs

**Does the buyer need a password?**

In the Shopify app version, no: Shopify's customer accounts sign them in with a one-time code sent to their email. In the SparkLayer Dashboard version, they create their trade account from the invite email.

**Can I change the invite email?**

In the Shopify app, Shopify sends it: click **Edit the email in Shopify** in the **Invite a buyer** box. The SparkLayer Dashboard's invite is sent by SparkLayer in your store's name.

**Can I invite someone who already has an account?**

No: you'll see "That buyer already has an account". Move them to the right customer group by changing their tags in Shopify instead.

**What if the buyer hasn't received their invite?**

Check the email address at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app and ask them to check their spam folder. In the Shopify app, you can resend Shopify's invite from the customer in your Shopify admin.


---

# Find and manage customers

URL: https://docs.sparklayer.io/help/customers/managing-customers

Find a B2B customer, check their access, customer group, credit and addresses, invite new buyers and fix customer sync errors in SparkLayer.

> **Quick summary**
>
> - **Customers** lists every B2B customer who can order on your store, with their **Access** (**Standard** or **Limited**, or **Invited** if they haven't accepted an invite yet) and customer group. Find it at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app.
> - Click **Invite buyer** to [invite someone new](https://docs.sparklayer.io/help/customers/invite-buyers.md). A banner at the top tells you when the customer sync found records that need fixing.
> - Open a customer to see what SparkLayer holds for them: company, customer group, credit, role, company users, addresses and IDs. You change their **Role** here. Everything else comes from your store.
> - Available on every plan.## How it worksSparkLayer doesn't hold its own customer accounts. It syncs your B2B customers from your eCommerce platform (on Shopify, customers tagged `b2b`) and shows them here. Use it to check what each one sees when they sign in.Where customer data comes from:

1. **Your platform**: The customer, their tags and their company live in your store's admin
2. **Customer sync**: SparkLayer imports B2B customers automatically, and tells you about any it couldn't
3. **Customers**: You check their access, group, credit and addressesTo change most details, edit the customer in your platform, and the change syncs to SparkLayer. The exception is the customer's [role](#make-a-customer-a-sales-agent), which you set here.## Find a customer1) Go to **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app.
2) Search by name, email or company.
3) Click the customer's name, or **View**, to open them.## The Customers screenThe Customers screen lists every B2B customer who can order on your store. Go to **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app.| Part                | What it shows / does                                                                                       |
| --- | --- |
| **Open in Shopify** | Opens **Customers** in your Shopify admin. |
| **Invite buyer** | Opens **Invite a buyer**. See [Invite a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md). |
| Sync banner | Shown when the last customer sync had problems. See [Fix customer sync errors](#fix-customer-sync-errors). |
| Search | Type a name, email or company (**Search by name, email or company**). |
| **Name** | The customer's name, with their company underneath. Click it to open the customer. |
| **Email** | The email address they sign in with. |
| **Access** | **Standard** or **Limited**, or **Invited** (see below). |
| **Group** | Their [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md). Sales agents show **Base**. |
| **View** | Opens the customer. |If nothing matches your search, the list says **No customers found** ("Try a different name or email.").### Access| Access | What it means |
| --- | --- |
| **Standard** | They can sign in and place orders. |
| **Limited** | They can build orders, but their orders need approving before they're placed, as a [limited company user](https://docs.sparklayer.io/help/customers/company-users.md#limited-access). |
| **Invited** | You've [invited them](https://docs.sparklayer.io/help/customers/invite-buyers.md), and they haven't created their account yet. |## A customer's pageA customer's page shows everything SparkLayer holds for them. To open it, click the customer's name or **View**. To open the same customer in your Shopify admin, click **View in Shopify**. An empty value shows **None set**.| Card | What it shows |
| --- | --- |
| **Basic information** | **Email**, **Company**, **Customer group**, **Price list override** (a price list for this customer only, see [Prices for one customer](https://docs.sparklayer.io/help/pricing/customer-pricing.md)) and **Sales agents who can see them**. |
| **Financial details** | **Discount percentage** and **Accounting ID** (see [advanced account settings](https://docs.sparklayer.io/help/customers/account-and-addresses.md#advanced-account-settings)). Under **Payment on account**: **Balance**, **Credit limit**, **Net terms** and **Currency**. See [Credit limits and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md). |
| **Role** | Whether the person is a customer, a sales agent or a sales administrator. See [Make a customer a sales agent](#make-a-customer-a-sales-agent). |
| **Company users** | "Everyone at this customer's company, and their roles." With none, it suggests adding company users, with **Learn more**. See [Company users](https://docs.sparklayer.io/help/customers/company-users.md). |
| **Addresses** | **Default shipping address**, **Default billing address** and **Other addresses**. |
| **Identifiers**       | **Platform ID** (the customer's ID in your platform), **Legacy ID** and **Internal ID** (SparkLayer's own ID).                                                                                                                                                                                                                   |**Sales agents who can see them** lists the agents allowed to see this customer's customer group, plus any agents who can see every customer. See [Sales agents](https://docs.sparklayer.io/help/sales-reps.md).The customer page doesn't show which [company locations](https://docs.sparklayer.io/help/customers/company-locations.md) a person is in, or their location roles. Check those on each location's page.## Change a customer's detailsCustomer information comes from your connected platform. To change fields such as the email address, name or company, edit the customer in your platform (on Shopify, click **View in Shopify**) and the change syncs to SparkLayer.**Shopify only:**

Fields such as the accounting ID and default addresses can also be set with metafields on Shopify: see [advanced account settings](https://docs.sparklayer.io/help/customers/account-and-addresses.md#advanced-account-settings).## Make a customer a sales agentA sales agent is a customer with a sales agent role. To give someone sales agent access:1) Open the customer and go to **Role** ("Assign a role to manage permissions for this person.").
2) Choose a role.
3) Click **Save** in the bar at the top. You'll see "Role saved".| Role                    | What they can do                                                                                    |
| --- | --- |
| **Customer** | "Can log in and place orders." |
| **Sales agent** | "Can place orders and manage addresses, shopping lists, and company access on behalf of customers." |
| **Sales administrator** | "All sales agent permissions, plus the ability to edit order prices and create new customers." |
| Your own roles          | Any [custom role](https://docs.sparklayer.io/help/sales-reps/roles.md) you've created, shown as "Custom sales rep role."         |To remove sales agent access, choose **Customer** and save.Sales agents need the Starter plan or above. Below Starter, choosing an agent role shows what sales agents do and how to upgrade.If you've used all the sales agents on your plan, you'll see "You've used all" and your plan's number of agents. Change another agent's role to **Customer**, or upgrade. See [Sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md) and [Your plan](https://docs.sparklayer.io/help/dashboard/plan-and-features.md).## Remove a customer from B2BOnce a customer has synced to SparkLayer, removing the `b2b` tag (or label) in your platform doesn't remove them from SparkLayer. It doesn't take them out of their customer group either. They stay at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app with the same group.To remove customers you no longer want in SparkLayer, [contact our support team](https://docs.sparklayer.io/help/support.md) with their email addresses. We can remove them one at a time or in bulk.To move a customer to another group instead, change their group tag: see [Assign customers to a customer group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group).## Fix customer sync errorsSparkLayer syncs your customers in full now and then, and syncs changes in between (a partial sync). When a sync finds records it can't use, a warning banner appears at the top of Customers. For example:> **Customers sync completed with 3 errors**
> We synced your customers to SparkLayer, but some records need fixing.The banner also gives the times of the last full and partial syncs. Home shows the same problem in your briefing ("customers didn't sync from Shopify"), with **Show errors**.To fix them:1) Click **Show errors**. **Customer sync errors** lists each customer's name, email and the problem.
2) Click **Open customers in Shopify** and fix each record there.The fixed customers sync on the next partial sync. You don't need to do anything else.| Example problem                              | How to fix it                                            |
| --- | --- |
| Missing a default shipping address | Add an address to the customer and make it the default. |
| Tagged `b2b-trade` but no first or last name | Add the customer's first and last name. |
| Tax exemption ID is not valid for DE         | Correct the tax exemption ID for the customer's country. |The banner is a warning, not an error: the sync worked for everyone else. Close it with **×** and it stays hidden until the next sync.## FAQs**Why is a customer missing from the list?**

Only B2B customers are synced. Check the customer is marked as B2B in your platform (on Shopify, tagged `b2b`) and has an email address and a default address. If the sync banner is showing, click **Show errors** to see whether they're listed.

**What do I do when a customer shows Invited?**

They haven't created their account yet. Ask them to check their email for the invite, or [send another](https://docs.sparklayer.io/help/customers/invite-buyers.md). Once they've signed in, their access changes.

**Can I edit a customer's email or company in SparkLayer?**

No. Change them in your eCommerce platform and they sync across to SparkLayer.

**How do I move a customer to another customer group?**

Change their tags (or labels) in your platform. See [Assign customers to a customer group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group). If they're in a company, the company's customer group applies instead. Change it on the [company page](https://docs.sparklayer.io/help/customers/companies.md#prices-and-rules).

**I removed the b2b tag but the customer is still in SparkLayer**

That's expected. Removing the tag doesn't remove a customer who has already synced, or change their customer group. Ask our team to remove them: see [Remove a customer from B2B](#remove-a-customer-from-b2b).

**Where did the customer data lookup go?**

Customer sync now lives on this screen: the banner shows the last full and partial sync and any errors, and **Show errors** lists the records to fix. To check one customer, search for them here and open their page.


---

# Customer groups

URL: https://docs.sparklayer.io/help/customers/customer-groups

Set the price lists, payment methods, order limits and other rules for each B2B customer group, and see how groups inherit from the Base group.

> **Quick summary**
>
> - A customer group is a set of rules shared by a set of B2B customers: which [price lists](https://docs.sparklayer.io/help/pricing.md) they see, which payment methods they can use, their order limits, and settings such as address editing and stock display.
> - Manage groups at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app. Every store has a **Base customer group** that applies to all B2B customers. Every other group inherits the Base group's rules unless you override them.
> - Each customer belongs to one group. Add buyers by [inviting them](https://docs.sparklayer.io/help/customers/invite-buyers.md) and choosing the group, or in your eCommerce platform. On Shopify, tag them `b2b` plus the group's tag, for example `b2b-trade`. See [Add customers to a group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md).
> - A [company](https://docs.sparklayer.io/help/customers/companies.md) or [location](https://docs.sparklayer.io/help/customers/company-locations.md) can be put in a group too. Customer groups are on every plan.## How it worksB2B customers usually order on agreed terms. A new customer might only be allowed to pay by card. A long-standing customer might pay on account with 30-day terms and a lower price list. With customer groups, you set those rules once and they apply to every customer in the group.How a customer gets their B2B rules:

1. **Add them to a group**: Tag them `b2b` plus the group's tag, such as `b2b-trade`, or invite them and choose the group
2. **SparkLayer syncs**: SparkLayer imports the customer and matches their tags to a customer group. With no group tag, they're in the Base group
3. **Customer signs in**: They see the group's prices, payment methods and ordering rules### The Base customer groupThe **Base customer group** covers all your B2B customers. If every B2B customer orders on the same terms, the Base group is all you need: set your rules there and they apply to everyone.When some customers need different rules, create more groups. Every new group **inherits** its rules from the Base group. A rule the group hasn't changed shows as **Inherited**. Override a rule to give the group its own setting. Anything you don't override keeps following the Base group.How rules are inherited:

1. **Base customer group**: Its rules apply to every B2B customer
2. **Another group**: Starts with the Base group's rules, shown as Inherited
3. **Override a rule**: Give the group its own setting, such as price lists. The rest still follow the Base groupSo to change something for every B2B customer, such as turning on stock display, change it in the Base group.### What can replace a group's settingsA group's settings are the starting point for its customers. A [company](https://docs.sparklayer.io/help/customers/companies.md#prices-and-rules) or [location](https://docs.sparklayer.io/help/customers/company-locations.md#prices-and-rules) can use a different customer group, or its own price list. A single customer can have their own price lists, with [customer pricing](https://docs.sparklayer.io/help/pricing/customer-pricing.md). See [What overrides what](https://docs.sparklayer.io/help/customers.md#who-sets-what).## Create a customer groupCreate a group for customers who need different rules from the rest. If all your B2B customers order on the same terms, you don't need one: set up the [Base customer group](#the-base-customer-group) instead.**BigCommerce only:**

On BigCommerce, you create customer groups in BigCommerce, and they sync to SparkLayer. See [Add customers to a group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group).1) 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 click **Create customer group**.
2) Enter a **Name**, for example `Trade`.
3) Choose a **Price list**, or leave **Base pricing** to use the Base group's prices.
4) Optionally, enter a **Minimum order value**, for example `250`.
5) Click **Create group**. You'll see "Customer group created".SparkLayer makes the group's **Handle (or ID)** from its name and creates its tag: a group called `Trade` gets the handle `trade` and the tag `b2b-trade`.**More detail**

- If you see "Give the group a name", "There's already a group with that name" or "The minimum order can't be negative", fix the field and click **Create group** again.
- The minimum order value becomes the group's **Order total limits** rule: see [Set order limits](#set-order-limits). 
- The handle is also the ID you use elsewhere, for example in [pack size rules per customer group](https://docs.sparklayer.io/help/storefront/quantity-rules.md), the API and ERP integrations. You can't change it.Then finish setting up the group:1) [Check its price lists](#assign-price-lists).
2) [Choose its payment methods](#choose-payment-methods).
3) Optionally, [change its order limits](#set-order-limits).
4) [Add customers to the group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md), for example by [inviting them](https://docs.sparklayer.io/help/customers/invite-buyers.md).
5) [Test as a B2B customer](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#test-as-a-b2b-customer) to check what they'll see.## Edit a customer group's rules1) 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.
2) Click the group's name. For the Base group, click **Edit** on the **Base customer group** card.
3) Find the rule under **Inherited rules** and click **Override** (on the Base group, **Customize**). The rule moves up to **Customized rules**.
4) Change the rule's settings.
5) Click **Save** in the bar at the top of the page. You'll see "Customer group saved". One save covers every rule you've changed.To hand a rule back, click **Reset** next to it under **Customized rules**, then save. On a group, the rule goes back to following the Base group. On the Base group, it goes back to SparkLayer's default.**More detail**

- **Customized rules** on a group: "Set for this group. Reset hands a rule back to the base group." With nothing customized, it says "Nothing customized yet. Everything below comes from the base group."
- **Inherited rules** on a group: "From the base customer group. Override one to change it for" the group. Each rule shows the value it inherits.
- On the Base group, **Customized rules** says "Every B2B customer gets these. Other groups inherit them unless they override them." and **Inherited rules** says "SparkLayer's defaults. Customize one to change it for every B2B customer."
- Click **Discard** in the bar at the top to throw away changes you haven't saved.### The group page| Part                 | What it shows / does                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| --- | --- |
| **Details** | The group's **Name** (fixed on the Base group), its **Handle (or ID)** ("Made from the name. Used by the API and ERP integrations.") and its **Customer tags**. The Base group's tag is `b2b` ("Applied to customers to turn on SparkLayer."). Other groups have `b2b` and their own tag ("Customers with these tags join this group."). **View customers** opens the customers with that tag in Shopify. A group also says how many customers it has. |
| **Customized rules** | The rules this group sets itself, each with **Reset**. |
| **Inherited rules** | Every other rule, with the value it inherits and **Override** (or **Customize** on the Base group). |
| **More actions**     | On a group (not the Base group): **Invite a buyer**, **Edit base customer group** and **Delete group**.                                                                                                                                                                                                                                                                                                                                                |## The customer groups screenThe customer groups screen shows the Base customer group and every other group, with what each one sets. 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. In the SparkLayer Dashboard, it's **Groups** in the sidebar. In the Shopify app, it's the **Customer groups** tab.**Base customer group** comes first: "Every B2B customer gets these settings. Groups inherit them unless they override one." Click **Edit** to open it. Four tiles sum it up: its **Shopify tag** (`b2b`), its **Price list**, its **Payment methods** and any **Other settings** it customizes.**What the Base customer group tiles show**

| Tile | What it shows |
| --- | --- |
| **Shopify tag** | `b2b`, the tag every B2B customer has. |
| **Price list** (or **Price lists**) | The Base group's price lists, or **Retail prices** if it has none. |
| **Payment methods** | The payment methods it allows. |
| **Other settings** | Any other rules it customizes, such as **Address management**. |**Additional customer groups** lists your other groups:| Column | What it shows |
| --- | --- |
| **Group** | The group's name, with its tag underneath, for example "Tag: b2b-trade". Click the name to open the group. |
| **Customers** | How many customers are in the group. |
| **Price list** | The group's own price lists, or **Inherited**. |
| **Payment methods** | The group's own payment methods, or **Inherited**. |
| **Order limit**     | The group's minimum order, for example "$250 minimum", or **Inherited**.                                   |With no other groups, it says **No customer groups yet**: "Every B2B customer gets the base settings until you add a group."**Common tasks**

**Common tasks** shortcuts the usual jobs: **Create a customer group**, **Add a buyer to a group** (opens [Invite a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md)), **Give a group its prices**, **Set a minimum order** and **Tag customers in Shopify**.## What a customer group controlsEach group has the same 11 rules.| Rule                                                     | What it does                                               | When it's inherited, it shows                             |
| --- | --- | --- |
| [Price lists](#assign-price-lists) | "Choose which price lists this group uses." | The Base group's price lists, or **Retail prices** |
| [Payment methods](#choose-payment-methods) | "Choose which payment methods show at checkout." | The Base group's payment methods |
| [Order quantity limits](#set-order-limits) | The minimum or maximum number of items in the whole order. | **No quantity limits set** |
| [Order total limits](#set-order-limits) | "The order total buyers must reach before checking out." | **No total limits set** |
| [Stock display](#show-stock-levels) | "What buyers see about stock." | **Availability: On, Pre-order: On, Units: Off, Max: 100** |
| [Stock location](#set-a-stock-location) | "Which inventory locations buyers can order from." | **The stock location feature isn't on** |
| [Credit settings](#block-orders-over-the-credit-limit) | "What happens when a buyer reaches their credit limit." | **Checkout blocked if limit exceeded** |
| [Quoting engine](#let-customers-request-quotes) | "Whether buyers can request quotes." | **Buyers can request quotes** |
| [Checkout access](#disable-checkout) | "Whether buyers can check out." | **Checkout is enabled** |
| [Address management](#allow-customers-to-edit-addresses) | "Whether buyers can edit their addresses." | Whether buyers can edit addresses |
| [Recurring orders](#allow-recurring-orders)              | "Whether buyers can set up repeat orders."                 | **The recurring orders feature isn't on**                 |Most groups only need their own price lists and payment methods. Every other rule is optional, and follows the Base group until you override it: see [Optional rules](#optional-rules).## Assign price lists1) [Edit the customer group](#edit-a-customer-groups-rules). If **Price lists** is under **Inherited rules**, click **Override** (or **Customize** on the Base group).
2) Choose a price list. Each option shows its currency and name, for example **USD - Trade 20%**.
3) To add another, click **Add price list**. To remove one, click the bin icon next to it.
4) Click **Save** in the bar at the top.### When a product is in several price listsA group's price lists are numbered in order, and if a product is in more than one, the first list it's in wins. So put the most specific list first, and check this order first when a customer sees the wrong price. See [Which price list wins](https://docs.sparklayer.io/help/pricing/managing-pricing.md#price-list-order).### Prices from outside the groupSome customers can get prices from somewhere other than their group. A company or location can have its own price list: see [Companies](https://docs.sparklayer.io/help/customers/companies.md#prices-and-rules). An individual customer can have their own price lists or a percentage discount: see [Prices for one customer](https://docs.sparklayer.io/help/pricing/customer-pricing.md).## Choose payment methods1) [Edit the customer group](#edit-a-customer-groups-rules) and override **Payment methods**.
2) Tick the methods the group can use: **Pay by invoice**, **Payment on account** or **Card at checkout**. Then click **Save**.At checkout, the customer sees the methods their group allows, as **Pay by Invoice**, **Pay on Account** and **Pay Online by Card**. A group with only **Card at checkout** ticked shows card payment and nothing else. For what each method means, how the order arrives in your platform and how to rename or reorder them, see [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md) and [How orders arrive](https://docs.sparklayer.io/help/ordering/payment-methods.md#how-orders-arrive).**Shopify only:**

Under each method you tick, **Add rule** gives the method a discount or surcharge, or hides it, when an order meets your conditions. See [Payment method rules](https://docs.sparklayer.io/help/ordering/payment-method-rules.md).A company or location with **Pay later** off can only pay by card, whatever its group allows. See [Companies](https://docs.sparklayer.io/help/customers/companies.md#paying).## Set order limitsOrder limits stop a customer checking out until the whole order meets your rules: a minimum or maximum order total (**Order total limits**, per currency) or a minimum or maximum number of items (**Order quantity limits**). [Edit the customer group](#edit-a-customer-groups-rules), override the rule and save. For the steps, the checkout messages and how to change them, see [Set order limits](https://docs.sparklayer.io/help/storefront/quantity-rules.md#order-limit-rules).A minimum, maximum or pack size for one product isn't a group rule: it's a [quantity rule](https://docs.sparklayer.io/help/storefront/quantity-rules.md) set on the product, and can differ by group with [product settings](https://docs.sparklayer.io/help/storefront/quantity-rules.md#set-different-rules-for-each-customer-group).## Add customers to the groupEach customer belongs to one group. You add them in your eCommerce platform: on Shopify, with the `b2b` tag plus the group's tag, such as `b2b-trade`. Or [invite them](https://docs.sparklayer.io/help/customers/invite-buyers.md) and choose the group. For the steps on each platform, how to check a customer has synced and how to test as one, see [Add customers to a group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md).## Optional rulesThese rules are optional. Each one follows the Base group until you override it. Most groups only need price lists, payment methods and perhaps an order limit.### Allow customers to edit addressesAddress management controls whether customers can manage their own address book in the [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) and [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) interfaces.1) [Edit the customer group](#edit-a-customer-groups-rules) and override **Address management** (on the Base group, it's already customized).
2) Tick or untick the settings below, then click **Save**.| Setting                                            | What it does                                                                                                                         |
| --- | --- |
| **Allow address editing in My Account** | "Buyers can add or edit their addresses." |
| **Allow buyers to add and edit billing addresses** | "Buyers can set a default billing address." Untick it to stop billing address changes while still allowing shipping address changes. |If addresses are synced to SparkLayer from another system, such as an ERP, the sync may overwrite changes your customers make. [Contact us](https://docs.sparklayer.io/help/support.md) if you're unsure.### Block orders over the credit limitThe **Credit settings** rule decides what happens when a customer paying on account would go over their [credit limit](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md). By default, **Checkout blocked if limit exceeded**. To let a group order over its limit, override **Credit settings**, click **Configure** and turn off **Prevent placing an order if exceeding credit limit**. See [Let customers order over their credit limit](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md#let-customers-order-over-their-credit-limit).### Show stock levelsThe **Stock display** rule decides what a group's customers see about stock: availability, pre-order messages and, if you want, the number of units. By default, availability and pre-order messages are on and unit counts are off. To change it for every customer, edit the Base group. For the settings and what customers see, see [Show stock levels to customers](https://docs.sparklayer.io/help/storefront/stock-display.md#show-stock-levels-to-customers).### Set a stock locationStock location (also called inventory location) shows a customer group the stock from one location, such as the warehouse that serves their region. For example, with warehouses in London, Paris, Toronto and Madrid, you can show your Canada group the stock held in Toronto. Stock locations need the Growth plan or above.1) Turn on **Multi-location stock** at **Settings > Configurations > Ordering** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Ordering** in the Shopify app ("Choose which inventory locations customers can buy stock from."). Until it's on, the rule shows **The stock location feature isn't on**.
2) [Edit the customer group](#edit-a-customer-groups-rules), override **Stock location** and click **Configure**.
3) Select the location the group should use, then save.Things to know:* If you don't choose a location, customers see combined stock from all your locations.
* Stock locations only affect the stock **shown** to customers. They don't change which location your platform uses to fulfil the order.Your platform needs some setup too:**Shopify:**

SparkLayer syncs your active Shopify locations automatically. Set them up in Shopify first (see Shopify's guide to [locations](https://help.shopify.com/en/manual/locations)):

1. In your Shopify admin, go to **Settings > Locations** ([open in the Shopify admin](https://admin.shopify.com/settings/locations)) and check the locations you want to use for B2B customers are active.
2. Open each of those locations and, under **Fulfillment details**, tick **Fulfill online orders from this location**.
3. Optionally, review how Shopify chooses a location for each order at **Settings > Shipping and delivery > Order routing** ([open in the Shopify admin](https://admin.shopify.com/settings/shipping/order_routing)). Routing rules (such as **Minimize split fulfillments** or **Ship from the closest location**) run from top to bottom.

If you run retail and B2B from the same store (a [hybrid store](https://docs.sparklayer.io/help/glossary.md#hybrid-store)):

- Signed-in B2B customers can buy up to the stock held at their group's location. For example, if their group uses **London Warehouse** and it has 100 of product A, they can order up to 100.
- Assigning a location to B2B customers doesn't stop retail customers buying the same stock, depending on how your Shopify store is set up. To hold stock back, see reserving stock and minimum stock levels in [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md).

**Other platforms:**

Stock locations and their stock levels are managed through the [Stock API](https://docs.sparklayer.io/developers/api/stock.md).### Let customers request quotesIf you use the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md), the **Quoting engine** rule decides whether a group can request quotes. By default, **Buyers can request quotes**. Quotes are included on Pro and Enterprise, and are an add-on on Starter and Growth. See [Choose which customer groups can request quotes](https://docs.sparklayer.io/help/ordering/quoting.md#choose-which-customer-groups-can-request-quotes).### Disable checkoutTo stop a group checking out, override **Checkout access** and click **Configure**. By default, every customer group can check out once their order meets your rules (**Checkout is enabled**). A common use is with the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md): turn off checkout so the group can only submit a quote.### Allow recurring ordersThe **Recurring orders** rule decides whether a group's buyers can set orders to repeat on a schedule.1) Turn on **Recurring orders** at **Settings > Configurations > Ordering** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Ordering** in the Shopify app ("Customers can set orders to repeat on a schedule."). Until then, the rule shows **The recurring orders feature isn't on**.
2) [Edit the customer group](#edit-a-customer-groups-rules), override **Recurring orders** and click **Configure**.## Delete a customer groupYou can't delete a customer group while it still has customers. Move them to another group first, for example the Base customer group, by changing their tags in your platform. See [Add customers to a group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group). On Shopify, **View customers** on the group's page lists everyone with its tag.Once the group is empty:1) Open the group.
2) Click **More actions**, then **Delete group**.
3) Click **Delete group** to confirm.This can't be undone. You can't delete the Base customer group.Moving a customer to another group doesn't remove them from SparkLayer. To remove customers altogether, see [Remove a customer from B2B](https://docs.sparklayer.io/help/customers/managing-customers.md#remove-a-customer-from-b2b).## FAQs and troubleshootingIf a customer sees the wrong prices, payment methods or shipping, check their tags and group first: see [Add customers to a group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#troubleshooting).**Can a customer be in more than one customer group?**

No. Each customer belongs to one customer group. To give a customer prices from several price lists, assign several lists to their group, or give the customer their own in [Prices for one customer](https://docs.sparklayer.io/help/pricing/customer-pricing.md). See [Add customers to a group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group).

**Can a group inherit from a group other than Base?**

No. Every group inherits from the Base customer group. Rules you override on a group apply to that group only.

**Why can't I delete a customer group?**

A group can't be deleted while it still has customers. Move them to another group, such as Base, then delete it. See [Delete a customer group](#delete-a-customer-group).

**Why didn't a group change when I changed the Base group?**

The other group overrides that rule, so it no longer inherits it. Open the group and click **Reset** on the rule to follow the Base group again.

**Which price is used when a SKU is in several price lists?**

The first price list, in the order shown on the group, that contains the SKU. See [Which price list wins](https://docs.sparklayer.io/help/pricing/managing-pricing.md#price-list-order).

**Do order limits include tax?**

No. Order total limits use net prices, before tax, unless you show [tax-inclusive prices](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-tax-inclusive-prices). See [Set order limits](https://docs.sparklayer.io/help/storefront/quantity-rules.md#order-limit-rules).

**Does a stock location change where orders are fulfilled from?**

No. It only changes the stock customers see. Your platform's own settings, such as Shopify order routing, decide where orders are fulfilled from.


---

# Add customers to a group

URL: https://docs.sparklayer.io/help/customers/add-customers-to-a-group

Put B2B customers in the right customer group with a tag or label in your eCommerce platform, check they've synced, then sign in as one to test.

> **Quick summary**
>
> - Each B2B customer belongs to one [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md), which sets their prices, payment methods and ordering rules.
> - You add customers to a group in your eCommerce platform. On Shopify, tag them `b2b` plus the group's tag, for example `b2b-trade`. Or [invite them](https://docs.sparklayer.io/help/customers/invite-buyers.md) from **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app and choose the group.
> - Check SparkLayer has matched them to the right group at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app, then sign in as a test customer to see what they'll see.
> - Works on every plan. On Shopify, new customers can also [apply for a trade account](https://docs.sparklayer.io/help/guides/approve-trade-applications.md) for you to approve.

## Ways to add customers

| If you're adding | Do this |
| --- | --- |
| **One customer**, or moving one to another group | Change their tags or labels in your platform. See [Add a customer to a group](#assign-customers-to-a-customer-group). |
| **Your existing trade customers**, all at once (Shopify) | Follow [Move your existing wholesale customers onto SparkLayer](https://docs.sparklayer.io/help/guides/move-existing-customers.md): tag them in bulk, bring across their terms, then ask them to sign in. |
| **New customers who apply** for a trade account (Shopify) | Follow [Let new trade customers apply, and approve them](https://docs.sparklayer.io/help/guides/approve-trade-applications.md). Approving an application creates the customer in the group you choose. |
| **A new buyer you invite** | [Invite them](https://docs.sparklayer.io/help/customers/invite-buyers.md) and choose the group. SparkLayer adds them to Shopify with the group's tag for you. |

## Add a customer to a group

A customer can belong to only one customer group. To give a customer more than one price list, [assign several price lists](https://docs.sparklayer.io/help/customers/customer-groups.md#assign-price-lists) to their group, or [give the customer their own](https://docs.sparklayer.io/help/pricing/customer-pricing.md). If different customers need different mixes of price lists, create one group for each combination, for example **Trade** with the Trade list, and **Trade and clearance** with the Trade and Clearance lists.

To add a customer to a group, if they already have an account, or to move them to another group, change their tags or labels in your platform:

**Shopify:**

SparkLayer uses Shopify **customer tags**. When a tagged customer signs in to your store, they see their group's prices, payment methods and rules.

- **Every B2B customer has the `b2b` tag**, even if they're also in another group.
- **Other groups need their own tag as well.** You'll find it under the group's name at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app, for example "Tag: b2b-trade".
- **You can't swap `b2b` for your own tag**, such as `trade-approved`. SparkLayer only recognises `b2b` plus the group's tag.
- **Copy the group's tag exactly**, as it shows under the group's name. A tag that's nearly right, such as one with part of the prefix missing, matches no group and leaves the customer in Base.
- **No more than two B2B tags per customer.** `b2b` and `b2b-trade` is correct; `b2b`, `b2b-trade` and `b2b-vip` is not.

To tag a customer:

1. In your Shopify admin, go to **Customers** ([open in the Shopify admin](https://admin.shopify.com/customers)) and open the customer.
2. In the **Tags** box, type `b2b` and choose it, or add it as a new tag.
3. To add them to another group, also add its tag, for example `b2b-trade`. If the tag doesn't exist yet, create it as a new tag and you can reuse it for other customers.
4. Save the customer.

To tag many customers at once, or add a new customer from scratch, see [Add B2B customers on Shopify](https://docs.sparklayer.io/help/platforms/shopify/invite-customers.md).

People at a 

[company](https://docs.sparklayer.io/help/customers/companies.md)

 get the customer group set on the company or their 

[location](https://docs.sparklayer.io/help/customers/company-locations.md)

.

**Wix:**

SparkLayer uses Wix contact **labels**. It only syncs contacts that have the `b2b` label and are **Site Members**.

1. In your Wix dashboard, go to **Customers & Leads > Contacts** and create or edit a contact.
2. Add a valid address and fill in every address field. Note the email address: the customer uses it to sign in.
3. Click **Add Label** and add `b2b`. For a group other than Base, also add that group's label exactly as shown at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app, for example `b2b-additional-group`.
4. Check the contact is a **Site Member** (shown under **Member info**), so they can sign in to your store.

Don't edit a label after you've added it. Once at least one contact has a group's label, you can manage that group's rules at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app.

**Other platforms:**

| Platform | How customers join a group |
| --- | --- |
| BigCommerce | SparkLayer syncs your BigCommerce customer groups whose names start with `B2B`, once at least one customer is in them. Assign customers to those groups in BigCommerce. See [Install on BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce/install.md). |
| WooCommerce | Give the WordPress user a **SparkLayer Role** that matches the group, such as "SparkLayer B2B: Base". See [Install on WooCommerce](https://docs.sparklayer.io/help/platforms/woocommerce/install.md). |
| Magento | SparkLayer creates a Magento customer group, prefixed "B2B", for each group you create. Assign customers to it in Magento. See [Install on Magento](https://docs.sparklayer.io/help/platforms/magento/install.md). |

Moving a customer to another group doesn't remove them from SparkLayer. To remove customers altogether, see [Remove a customer from B2B](https://docs.sparklayer.io/help/customers/managing-customers.md#remove-a-customer-from-b2b).

## Check a customer has synced

To check SparkLayer has picked up a customer in the right group, find them at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app. The **Group** column shows the customer group they've been matched to. Open them to see more. See [Find and manage customers](https://docs.sparklayer.io/help/customers/managing-customers.md).

If a customer is missing, check the sync banner at the top of Customers and click **Show errors**: see [Fix customer sync errors](https://docs.sparklayer.io/help/customers/managing-customers.md#fix-customer-sync-errors).

## Test as a B2B customer

Before your customers start ordering, place a test order as a B2B customer and check their group's rules.

**Shopify only:**

In the Shopify app, [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order) does this for you: it creates a test customer with the `b2b` tag, gives them a price list and opens your store signed in as them.

- **Prices** match the group's price lists.
- **Payment methods** at checkout are the ones the group allows.
- **Order limits** stop checkout when the order is below the minimum or above the maximum.

To test by hand:

**Shopify:**

**Step 1.** **Turn on customer accounts**

In your Shopify admin, go to **Settings > Customer accounts** ([open in the Shopify admin](https://admin.shopify.com/settings/customer_accounts)) and choose either **Customer accounts** or **Legacy accounts**. Both work with SparkLayer.

**Step 2.** **Add a test customer**

In Shopify, go to **Customers** ([open in the Shopify admin](https://admin.shopify.com/customers)), open or add a customer with an email you can sign in to, fill in every field **including the address**, and add the `b2b` tag plus the group's tag. Or [invite a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md) with an email you can sign in to, and choose the group you're testing.

**Step 3.** **Sign in as the customer**

Go to your store's login page (for example `www.yourstore.com/account`) and sign in. With Customer accounts, enter the code sent to your email. With Legacy accounts, activate the account from the invite email first. SparkLayer loads and you can browse as a B2B customer. If the login page doesn't load, check customer accounts are turned on.

**Other platforms:**

Create a test customer in your platform, add them to a B2B group as described in [Add a customer to a group](#assign-customers-to-a-customer-group), then sign in to your store as them. See your platform's install guide under [Platforms](https://docs.sparklayer.io/help/platforms.md) for details.

## Troubleshooting and FAQs

A customer seeing the wrong prices, payment methods or shipping usually comes down to their tags or their group.

**Diagnose: Wrong prices, payment methods or shipping for a customer?** Check the customer’s tags and customer group.

1. **What is the customer seeing?** Pick the closest match.
   - Wrong prices: go to question 2
   - Wrong payment methods: go to question 2
   - Wrong shipping options: go to question 2
2. **Are you checking while signed in as the customer?** B2B prices, payment methods and shipping only apply once a B2B customer signs in.
   - Yes: go to question 3
   - No / not sure: go to fix A (Sign in as the customer first)
3. **Does the customer have the `b2b` tag?** Check the spelling exactly, with no extra spaces or characters. Where to look: Customers > select the customer > Tags (Shopify admin).
   - Yes: go to question 4
   - No: go to fix B (Add the `b2b` tag)
4. **Should they be in a customer group other than Base?** Customers with only the `b2b` tag are in the Base customer group.
   - Yes: go to question 5
   - No, Base is right: go to question 6
5. **Does the customer have that group’s tag, spelt exactly as it is on the group?** Each group shows its Shopify tag. It’s usually `b2b-` followed by the group’s handle, for example `b2b-vip`. Where to look: Customers > Groups (SparkLayer).
   - Yes: go to question 7
   - No: go to fix C (Fix the group tag)
6. **Are the price lists / payment methods / shipping set up on that customer group?** Open the group and check its settings. Where to look: Customers > Groups (SparkLayer).
   - Yes: go to question 8 for prices; fix D (Tags look right: check plan and terms) for payments; fix E (Tags look right: check your shipping setup) for shipping
   - No: go to fix F (Set them up on the group)
7. **Does the customer have only `b2b` and that one group tag?** Look for older group tags left over from a previous setup. A customer can only be in one group. Where to look: Customers > select the customer > Tags (Shopify admin).
   - Yes: go to question 6
   - No, there are others: go to fix G (Remove the extra tags)
8. **Is the product in more than one of the group’s price lists?** SparkLayer uses the first price list on the group that contains the SKU. An automatic list covers every product, so if it’s first it always wins. Where to look: Customers > Groups (SparkLayer).
   - Yes: go to fix H (Put the most specific price list first)
   - No / not sure: go to fix I (Tags look right: check the price itself)

**Fixes**

- **A. Sign in as the customer first** Signed-out visitors see retail prices and checkout. Sign in as the customer, or use Place a test order, and check again. Where: Orders > Place a test order (SparkLayer).
- **B. Add the `b2b` tag** Without it the customer shops as retail, with retail prices and checkout. Add the tag and save. Where: Customers > select the customer > Tags (Shopify admin).
- **C. Fix the group tag** A tag that doesn’t match a group is ignored, and the customer gets Base settings. Copy the tag from the group and add it to the customer. If the group doesn’t exist yet, create it. Where: Customers > Groups (SparkLayer).
- **D. Tags look right: check plan and terms** Some payment methods depend on your plan, and Pay on Account needs the customer’s credit limit and terms set. See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md).
- **E. Tags look right: check your shipping setup** The customer is in the right group, so the cause is in your shipping settings. Next: Shipping not working as expected?
- **F. Set them up on the group** Add the missing price lists / payment methods / shipping to the customer’s group, save, then sign in as the customer to check. Where: Customers > Groups (SparkLayer). See [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md).
- **G. Remove the extra tags** SparkLayer only uses `b2b` and one customer group tag. Extra B2B or group tags can put the customer in the wrong group. Remove the ones you don’t need, save, and ask them to sign out and back in. Where: Customers > select the customer > Tags (Shopify admin).
- **H. Put the most specific price list first** The first list on the group that contains the SKU sets its price. Move your specific lists above any automatic list, and save. Where: Customers > Groups (SparkLayer). See [Price list order](https://docs.sparklayer.io/help/pricing/managing-pricing.md#price-list-order).
- **I. Tags look right: check the price itself** The customer is in the right group, so the difference is coming from the price list or your tax settings. Next: Prices or tax looking wrong?

**Can a customer be in more than one customer group?**

No. Each customer belongs to one customer group. If you need a customer to see prices from several price lists, assign several price lists to their group, or give the customer their own price lists in [Prices for one customer](https://docs.sparklayer.io/help/pricing/customer-pricing.md). If customers need different mixes of price lists, create one group for each combination.

**What happens if a customer has no group tag?**

They're in the [Base customer group](https://docs.sparklayer.io/help/customers/customer-groups.md#the-base-customer-group), as long as they have the `b2b` tag (or your platform's equivalent). Without it, they aren't a B2B customer and see your retail store.


---

# Company users

URL: https://docs.sparklayer.io/help/customers/company-users

Let B2B customers invite colleagues to one company account to share orders, shopping lists and addresses, with Limited users whose orders need approval.

> **Quick summary**
>
> - Company users (also called sub-accounts or company roles) let a B2B customer invite colleagues to their company account. Everyone shares the company's orders, shopping lists and addresses, and orders at the same prices.
> - It's on by default. Turn it on or off with **Company users** at **Settings > Configurations > Ordering** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Ordering** in the Shopify app. Customers invite colleagues from the **Company Users** section of My Account.
> - Invited users are **Standard** (can place orders) or **Limited** (orders go to the main user for approval). Company users are on every plan; order approval workflows need the Growth plan or above.
> - On BigCommerce, WooCommerce and Magento, invited users don't receive a confirmation email. See [Compare platforms](https://docs.sparklayer.io/help/platforms/compare.md).

## How it works

The customer who sends the invitations becomes the **main user** (the account owner, or admin). They decide who has access to the company account, and approve orders from limited users. Each user they invite signs in with their own email address, but orders on the company's account at the main user's prices.

How company users join an account:

1. **Turn it on**: Company users is on in Settings > Configurations
2. **Main user invites**: A B2B customer invites a colleague from My Account and picks a role
3. **Colleague signs in**: They activate their account, or sign in with an existing one
4. **Shared account**: Everyone sees the company's orders, shopping lists and addresses

Users of the same company share most of the account:

| Area | Shared? |
| --- | --- |
| **Order history** | Yes. Users see every order placed for the company, can check its status and re-order. |
| **Shopping lists** | Yes. Users can view and delete the company's shopping lists. |
| **Address book** | Yes. Users can view, edit and delete all the company's addresses. |
| **Shopping cart** | No. Items in one user's order aren't shared with other users. |

Company users can be used alongside [sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md): a sales agent can add users to a customer's company in the same way a main user does.

In the app, each person's role shows in the **Access** column at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app: **Standard** or **Limited**. Open a customer to see everyone at their company under **Company users**.

**Shopify only:**

On Shopify, a [company](https://docs.sparklayer.io/help/customers/companies.md) also has **Admins**, who can invite people and manage its locations. Each [location](https://docs.sparklayer.io/help/customers/company-locations.md#people-and-location-roles) also gives its people a role of its own.

## Turn on company users

Company users is on by default. To check it, or turn it off:

1. Go to **Settings > Configurations > Ordering** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Ordering** in the Shopify app.
2. Turn **Company users** on or off ("Customers can create teams that share orders, shopping lists and addresses.").
3. Click **Save** in the bar at the top of the page.

When it's on, a **Company Users** section appears at the bottom of the [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) for every B2B customer. You can't turn it on for some customers only.

## Roles

Each company user has a role, which decides whether they can place orders themselves. The main user chooses it under **User role** when they invite someone.

| Role | What the user can do |
| --- | --- |
| **Standard** | Place orders and see all activity in the shared company account. |
| **Limited** | Add items to an order but not complete it. Their orders are sent to the main user for approval. |

## Invite a company user

Customers invite colleagues from your store, not from the SparkLayer app. You may want to explain these steps to your customers when you launch the feature.

1. In My Account, go to the **Company Users** section and click **Invite new user**.
2. Enter the colleague's **First Name**, **Last Name** and **Email**. They'll sign in with this email address.
3. Under **User role**, choose **Standard** or **Limited** (see [Roles](#roles)).
4. Click **Create Company User**.

What happens next depends on whether the person already has an account on your store:

| Account status | What happens |
| --- | --- |
| No account | They're emailed an invitation to set a password, which activates their account and adds them to the company. |
| Has an account | They sign in with their existing details to join the company. |
| Already a B2B customer | They can't be invited as a company user. Link them to the company manually instead: see [Link users to a company manually](#link-users-to-a-company-manually). |

**Shopify only:**

On Shopify, the invitation is Shopify's **Activate account** email ("Activate your account"), which you can edit at **Settings > Notifications** ([open in the Shopify admin](https://admin.shopify.com/settings/notifications)). You can't send a custom SparkLayer email instead.

**BigCommerce and WooCommerce and Magento only:**

On BigCommerce, WooCommerce and Magento, invited users don't receive a confirmation email. Tell them the email address they've been invited with and ask them to use "Forgot password" to set a password.

## Sign in as a company user

An invited user sees the [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) as usual. A message at the top says "You're signed into a Company User account", and explains that activity is shared across the company. Under **My Details**, the **Company** shows the company name and the account owner, for example "SparkLayer (Your company account owner is Bob Jones)".

They browse and order at the prices set for the main user in [Pricing](https://docs.sparklayer.io/help/pricing.md). They check out in the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) with the same addresses, shipping methods and payment methods.

### How company user orders arrive in Shopify

**Shopify only:**

Orders are saved to the main user's account. By default, they arrive in Shopify as **draft orders**, with the customer's details on the right. The email of the user who placed the order is under **Additional details**, in the **Company User Email** field.

| Payment method | What happens |
| --- | --- |
| **Pay by Invoice** | A draft order is created for you to process. It stays a draft until payment is made. |
| **Pay on Account** | A draft order is created for you to process. It stays a draft until payment is made. |
| **Pay Online by Card** | A draft order is created and the customer is emailed to pay. It stays a draft until they do. |
| **Request for Quote** | A draft order is created for you to process. It stays a draft until payment is made. |

When the customer needs to pay, Shopify emails them their order with a **Complete your purchase** button. This uses the "Send invoice" feature of draft orders: see Shopify's guide to [sharing a checkout link](https://help.shopify.com/en/manual/orders/create-orders#share-checkout-link-with-customers). Once they pay, the order appears in your Shopify orders as paid. To change the email, edit the **Draft order invoice** template at **Settings > Notifications** ([open in the Shopify admin](https://admin.shopify.com/settings/notifications)).

If the customer hasn't paid, or you take payment another way, open the draft order in Shopify and click **Resend invoice**, or use **Collect payment** to mark it as paid.

## Approve orders from limited users

A limited user's orders wait for the main user to approve them before they reach you.

### What a limited user sees

When a limited user checks out, they see "This order needs to be reviewed". They submit the order with **Submit Order** instead of paying. SparkLayer holds it as a pending order, so you won't see it in your platform yet. Once the main user approves it, it becomes a normal order that you review, complete and fulfil as usual.

How an order from a limited user is approved:

1. **Limited user submits**: The order is saved for review with a P# reference
2. **Main user is emailed**: They open the order from the email or from My Account
3. **Complete or cancel**: Complete Order checks it out; Cancel Order removes it
4. **Limited user is told**: They get an email when the order is approved or changed

### Review orders as the main user

Orders waiting for approval appear in the main user's My Account under **Recent Activity**, on the **Requires approval** tab, with the status **Requires Approval**. Their reference starts with `P#` (for example `P#1264`), which sets them apart from other orders. To change it, use **Purchase ID prefix** and **Purchase ID postfix** at **Settings > Configurations > Store** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Store** in the Shopify app. See [Settings](https://docs.sparklayer.io/help/dashboard/settings.md).

The main user opens the order and, from the **Actions** menu, chooses:

| Action | What it does |
| --- | --- |
| **Complete Order** | Loads the order into a new cart so the main user can check out and place it. |
| **Cancel Order** | Cancels the order and removes it from the **Requires approval** list. |

SparkLayer sends emails at each stage, so neither user needs to be signed in to keep track:

| Email to | Sent when | What it contains |
| --- | --- | --- |
| **Main user** | A limited user submits an order. | Who placed it, a summary of up to five items with the totals, shipping method and address, and a **Review Order** button. |
| **Limited user** | The main user approves or changes their order. | An update on the order's status. |

The store name at the top of these emails comes from your eCommerce platform. To change it, edit **Store details** at **Settings > Configurations > Store** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Store** in the Shopify app: see [Settings](https://docs.sparklayer.io/help/dashboard/settings.md).

## Remove a company user

The main user removes a colleague from My Account:

1. Open the **Company Users** section.
2. Click the bin icon next to the user. They lose access to the company.

## Link users to a company manually

You can add a customer to a company yourself, for example when the person is already a B2B customer and can't be invited.

**Shopify:**

You link a customer by setting customer metafields in Shopify. SparkLayer can add the metafield definitions for you: 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 and, on the **Metafields** card, click **Configure**. Or add them yourself at **Settings > Metafields and metaobjects > Customers** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data/customer/metafields)). See [Shopify metafields and data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md).

1. Find the main user's customer ID. Open them in your Shopify admin: the ID is the number at the end of the page address. For example, in `https://your-shopify-store-url.com/admin/customers/6494756339930` the ID is `6494756339930`.
2. Open the customer you want to link and, under **Metafields**, set `parent_customer_id` to the main user's ID.
3. Optionally, set their role with the `role` metafield.
4. Give them the same B2B tags as the main user. For example, if the main user has `b2b` and `b2b-company-1`, add both.

**Lots of customers? Fill them in one table (Shopify):** in your Shopify admin, go to **Customers**, tick the customers and click **Edit customers**. Click **Columns**, tick the SparkLayer field under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

| Metafield | Type | Namespace and key | Value |
| --- | --- | --- | --- |
| Parent customer | Single line text | `sparklayer.parent_customer_id` | The main user's customer ID. |
| Role | Single line text | `sparklayer.role` | `main` for Standard, or `limited-customer` for Limited. |

**Other platforms:**

See the [developer docs](https://docs.sparklayer.io/developers.md) and [Metafields](https://docs.sparklayer.io/developers/data/metafields.md) for how to link customers on your platform.

## Customise the text

You can change the wording of the Company Users section by adding translations to your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting). This is a code change, so it's usually done by your developer or agency. See [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md).

**Code for your developer**

```javascript title="Core Script"
translations: {
  en: {
    "account.main.company-users.actions": "Actions",
    "account.main.company-users.title": "You're signed into a Company User account",
    "account.main.company-users.child-account-notice": "Any activity will be shared across all users from your company. This applies to orders, shopping lists, and addresses. Please speak to your company account owner if you have any queries.",
    "account.main.company-users.email": "Email",
    "account.main.company-users.delete-confirm-message": "Are you sure you want to remove this user from your company?",
    "account.main.company-users.delete-failed-message": "Failed to delete user.",
    "account.main.company-users.header": "Company Users",
    "account.main.company-users.invite-button-text": "Invite new user",
    "account.main.company-users.invite-user.header": "Invite new user",
    "account.main.company-users.invite-user.invite-sent": "User invite sent",
    "account.main.company-users.invite-user.invite-failed": "Sorry, something has gone wrong and we have not been able to invited this user",
    "account.main.company-users.invite-user.form.first-name": "First Name",
    "account.main.company-users.invite-user.form.last-name": "Last Name",
    "account.main.company-users.invite-user.form.email": "Email",
    "account.main.company-users.invite-user.form.send-invite": "Create Company User",
    "account.main.company-users.invite-user.form.cancel": "Cancel",
    "account.main.company-users.invite-user.form.description": "When you invite company users, any activity will be shared across your team including orders, shopping lists, and addresses. If the user you're inviting doesn't already have an account to login to our store, they'll receive an Account Activation email and they'll be asked to set a password to gain access. If they already have an account, they can login with their existing details by visiting the login page. If you're unsure about inviting users, please speak to your contact within our company."      
    }
  },
```

## Limitations

- **Invitation emails:** on Shopify, invited users receive Shopify's "Activate Account" email. You can't create a custom email for this.
- **All customers:** once company users is turned on, every B2B customer can invite users. You can't choose which customers have it.

## FAQs

**Do company users see the same prices as the main user?**

Yes. They order at the prices set up for the main user.

**Can I see who placed an order?**

Yes. On Shopify, the user's email is in the **Company User Email** field under **Additional details** on the order.

**Why can't I see an order from a limited user?**

It's waiting for the main user's approval and only reaches your platform once they complete it.

**What if someone can't be invited because they're already a B2B customer?**

Link them to the company with metafields instead: see [Link users to a company manually](#link-users-to-a-company-manually).


---

# Customise My Account

URL: https://docs.sparklayer.io/help/customers/account-and-addresses

Customise the SparkLayer My Account area: add custom My Details fields, rename order statuses, control address editing, show tracking and set login redirects.

> **Quick summary**
>
> - The [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) is where B2B customers see their details, orders and addresses. This page covers the settings that change what it shows and how it behaves.
> - Address editing is set per customer group, under **Address management** at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app. Order tracking details come from your eCommerce platform when you fulfil an order.
> - Most other options, such as custom fields and order status names, are set in your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting) or, on Shopify, with customer metafields. Your developer or agency usually does these. See [For developers](#for-developers).
> - Available on every plan.

## How it works

My Account brings together a customer's **My Details**, **Recent Activity** (orders, quotes and their statuses), **Shopping Lists**, **Address Book** and, if turned on, **Company Users**. Its data comes from your eCommerce platform. For example, on Shopify, tracking numbers you add when fulfilling an order appear on the customer's order details.

You change My Account in three ways:

| Where | Used for |
| --- | --- |
| The SparkLayer app | [Address editing](#allow-address-editing) per customer group, and [payment status](#show-payment-status) at **Settings > Configurations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations** in the Shopify app. |
| Core Script | [Custom My Details fields](#add-custom-fields-to-my-details), [order status names](#rename-order-statuses), the [shipping address summary](#show-the-shipping-address-on-orders) and the [account redirect](#change-where-customers-go-after-signing-in). See [Frontend integration](https://docs.sparklayer.io/developers/frontend.md). |
| Your platform | [Tracking details](#show-order-tracking-details), [custom order IDs](#show-a-custom-order-id) and [advanced account settings](#advanced-account-settings) such as accounting IDs. |

## Allow address editing

Address editing is on by default. Customers manage their own address book in My Account: they click **Add new address** to add one, or use the icons next to an address to edit or delete it.

To change it, edit the customer group's **Address management** settings at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app. You can turn off address editing completely. Or you can stop customers adding and changing billing addresses only, and still let them manage other addresses. See [Allow customers to edit addresses](https://docs.sparklayer.io/help/customers/customer-groups.md#allow-customers-to-edit-addresses).

| Setting in **Address management** | What it does |
| --- | --- |
| **Allow address editing in My Account** | Buyers can add or edit their addresses. |
| **Allow buyers to add and edit billing addresses** | Buyers can set a default billing address. |

**Shopify only:**

On Shopify, people ordering for a [company location](https://docs.sparklayer.io/help/customers/company-locations.md) use that location's address instead.

## Show order tracking details

Customers see tracking details on an order's details page, including for orders shipped in parts. They see a **Track shipment** link, the carrier and the tracking number.

**Shopify:**

When you fulfil an order in Shopify, enter the **Tracking number** and **Shipping carrier** under **Tracking information (optional)**. A third-party app can do this for you automatically. The details then appear in My Account.

**Other platforms:**

See the [developer docs](https://docs.sparklayer.io/developers.md).

## Show payment status

Alongside the order status, customers can see a **Payment** column showing whether each order is **Paid** or **Unpaid**. It's on by default. Turn it on or off with **Payments visibility** at **Settings > Configurations > Ordering** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Ordering** in the Shopify app ("Show the payment status of orders in the My Account area."). See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md).

## Change where customers go after signing in

When a signed-in B2B customer opens your store's own account page (for example `/account`), SparkLayer sends them to the SparkLayer My Account interface. You can send them somewhere else instead, such as a collection page.

**Shopify only:**

On Shopify with customer accounts (new accounts), you can do this without code:

1. In your Shopify admin, go to **Settings > Checkout** ([open in the Shopify admin](https://admin.shopify.com/settings/checkout)).
2. Under **Configurations**, click **Customize**.
3. Go to the **Orders** page, click **Apps** and turn on the **B2B Account Redirect** extension.
4. Optionally, add placeholder text to show customers while they're redirected, and the URL to send them to, such as a collection or landing page.

On any platform, including Shopify with legacy (classic) customer accounts, your developer or agency can add an `accountRedirect` to your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting) instead.

**Code for your developer**

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

**Shopify only:**

**Different pages for different customer groups (Shopify legacy accounts)**

With Shopify's legacy (classic) customer accounts, you can send each customer group to its own page, for example group ABC to `/collections/wholesale-page` and group XYZ to `/collections/wholesale-vip`. Replace the code above with Liquid code like this and change the tags and pages to suit:

```javascript title="Core Script"
accountRedirect: {
  urlRegex: /\/account/g,

  {% assign goTo = "/index" %}
  {% for tag in customer.tags %}
    {% if tag == "b2b-group-1" %}
      {% assign goTo = "/collections/wholesale-page" %}
    {% elsif tag == "b2b-group-2" %}
      {% assign goTo = "/collections/another-wholesale-page" %}
    {% endif %}
  {% endfor %}

  goTo: {{ goTo | json }},
},
```

## Other My Account features

These features also show in My Account, and have their own guides:

| Feature | What it does | See |
| --- | --- | --- |
| Account credit and balances | Shows the customer's credit, balance and payment terms. | [Credit limits and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) |
| Timeline and communications | Brings messages, internal notes, order events and email notifications for orders and [quotes](https://docs.sparklayer.io/help/ordering/quoting.md) into one place on the order details page. | [Order timeline and messages](https://docs.sparklayer.io/help/customers/timeline.md) |
| Links straight to an order | Takes a customer straight to an order's or quote's details from a link. | [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) |
| Invoices on orders | Attaches invoices, such as PDFs, to a customer's orders. | [Credit limits and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) |
| Imported and manual orders | Shows orders created outside the SparkLayer checkout, such as Shopify admin draft orders or imported history, in the customer's order history (Shopify). | [Show imported or manual orders in My Account](https://docs.sparklayer.io/help/guides/show-imported-orders.md) |

## For developers

The settings in this section are made in your SparkLayer [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting), or with metafields (extra fields on a customer or order record in your store). Your developer or agency usually makes them.

### Add custom fields to My Details

The **My Details** section shows the customer's email address, name, company and financial details, such as their account balance and payment terms. You can add your own fields, such as a website, phone number or account manager's email.

Add a `customAccountDetails` list to your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting). It works like [custom checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md).

```javascript title="Core Script"
customAccountDetails: [
  {
    title: "Website",
    value: "{{ customer.metafields.global.company_website }}",
    type: "website",
    displayText: "Visit Website",
  },
  {
    title: "Phone",
    value: "01234567890",
    type: "phone",
  },
  {
    title: "Email",
    value: "contact@sparklayer.io",
    type: "email",
    displayText: "Click to email",
  },
  {
    title: "Some normal text",
    value: "This is a normal value with no formatting",
  },
],
```

| Key | What it does |
| --- | --- |
| `title` | The label the customer sees, for example "Website". |
| `value` | The value. Set it directly or generate it, for example from a metafield or setting. |
| `type` | Optional. Turns the value into a link: `email` makes a `mailto:` link, `phone` makes a `tel:` link and `website` makes a link to the value. |
| `displayText` | Optional. Text to show instead of the value, for example `displayText: "Click here"` for a link. |

If you use [sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md), fields based on a customer metafield show the sales agent's value, not the customer's, when an agent is signed in as a customer.

### Rename order statuses

My Account shows each order's status, such as **Processing**, **Shipped**, **Part-Shipped**, **Cancelled** or **Requires Review**. See [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) for what each status means.

To change the names, add translations to your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting) (see [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md)):

```javascript title="Core Script"
translations: {
  en: {
    "account.order-status.incoming": "Incoming",
    "account.order-status.returned": "Returned",
    "account.order-status.cancelled": "Cancelled",
    "account.order-status.shipped": "Shipped",
    "account.order-status.part_shipped": "Part-shipped",
    "account.order-status.part_returned": "Part-returned",
    "account.order-status.varied": "Varied",
    "account.order-status.processing": "Processing",
    "account.order-status.awaiting_approval": "Requires approval",
    "account.order-status.awaiting_merchant": "Awaiting merchant",
    "account.order-status.archived": "Archived",
  }
},  
```

### Show the shipping address on orders

To show each order's shipping address under it in the order list, add this to the `display` object in your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting):

```javascript title="Core Script"
display: {
  orderListShowShippingAddress: true,
},
```

### Show a custom order ID

You can replace the order number customers see with your own (a "visible ID"), so order numbers match across your systems.

**Shopify only:**

On Shopify, this is set with a metafield: see [Shopify metafields and data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md).

### Add custom content with slots

Custom slots (or targets) are places in My Account, such as above **Recent Activity**, where you can add your own HTML. See [Custom slots](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md).

### Advanced account settings

Customer metafields give you finer control over account and address data, for example when a backend system such as an ERP needs specific customer IDs. Each one uses the namespace `sparklayer` with the key below.

| Setting | Key | Type | What it does |
| --- | --- | --- | --- |
| **Accounting ID** | `accounting_id` | Single line text | A unique account ID for the customer, for example from your ERP or accounts package. When set, it's added to the order's metadata in your eCommerce platform. |
| **Title** | `title` | Single line text | A title for the customer. |
| **Company Name** | `company_name` | Single line text | The customer's company name. |
| **Shipping Address ID** | `shipping_address_id` | Single line text | A unique shipping address ID. When set, it's the customer's default shipping address. |
| **Billing Address ID** | `billing_address_id` | Single line text | A unique billing address ID. When set, it's the customer's default billing address. |
| **Available Shipping Addresses by ID** | `available_shipping_address_ids` | JSON | The shipping addresses the customer can use, by Shopify address ID, as a list. For example `[9840404758756,9840404758756]`. |

To add them on Shopify, go to **Settings > Metafields and metaobjects > Customers** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data/customer/metafields)), as [Shopify metafields](https://docs.sparklayer.io/help/platforms/shopify/metafields.md) describes. On other platforms, see [Metafields](https://docs.sparklayer.io/developers/data/metafields.md).

**Lots of customers? Fill them in one table (Shopify):** in your Shopify admin, go to **Customers**, tick the customers and click **Edit customers**. Click **Columns**, tick the SparkLayer field under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

**Build the list of shipping address IDs**

Enter each Shopify address ID the customer can use, and copy the value into **Available Shipping Addresses by ID**:

## FAQs

**Can I stop customers editing their addresses?**

Yes. Turn off address editing in the customer group's **Address management** settings. See [Allow customers to edit addresses](https://docs.sparklayer.io/help/customers/customer-groups.md#allow-customers-to-edit-addresses).

**Why does a sales agent see their own value in a custom field?**

Custom My Details fields based on a customer metafield show the signed-in account's value. When a sales agent acts as a customer, that's the agent's account.

**Where do tracking numbers come from?**

From your eCommerce platform. On Shopify, add them when you fulfil the order.


---

# Order timeline and messages

URL: https://docs.sparklayer.io/help/customers/timeline

Turn on the order timeline so customers and sales agents can message each other, keep internal notes and see order events and edits on B2B orders and quotes.

> **Quick summary**
>
> - The timeline is a record on each order's details page, in date order. It holds messages between customers and your sales team, internal notes, order events and edits.
> - **Timeline and communications** at **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app lets customers and sales agents post messages and internal notes on orders. Quotes always allow messages. An order with entries, such as a payment, shows its timeline either way.
> - Available on every plan, and doesn't need the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md). Sending emails from your own domain needs the Pro or Enterprise plan.

## How it works

The timeline appears on the **Order Details** page of the [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md), for customers and sales agents. It covers:

- Standard B2B orders
- Orders placed by [sales agents](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md), including their draft orders
- [Quotes](https://docs.sparklayer.io/help/ordering/quoting.md)

Customers and sales agents post messages on the order. When a new message arrives, SparkLayer emails the other side. Sales agents can also save internal notes that customers never see. Order events, such as edits and status changes, are added automatically, so the timeline is a complete audit trail of the order.

How a message reaches the other side:

1. **Customer posts a message**: On the order's details page in My Account
2. **Your team is emailed**: The assigned sales agent, or your notification addresses if no agent is assigned
3. **Sales agent replies**: From the order's timeline, or by replying to the email
4. **Customer is emailed**: They sign in to read and reply

You can try it on our [B2B demo store](https://demo.sparklayer.io/pages/b2b-login-register).

## Turn on the timeline

1. Go to **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app.
2. Turn on **Timeline and communications** ("Customers and sales agents can send messages on quotes and orders.").
3. Click **Save** in the bar at the top of the page.

The setting controls posting, not whether the timeline shows:

- **Quotes** always have the timeline and its message box, whether or not the setting is on.
- **Orders** with the setting off still show their timeline when it has entries, such as payments, but customers and sales agents can't post messages or notes on them.

## Post a message or internal note

Customers and sales agents post from the order itself. Open an order in My Account and use the message box at the top of the **Timeline**.

| Who | Option | What it does |
| --- | --- | --- |
| Customer | Message box | Sends a message to your sales team. |
| Sales agent | **Notify customer** | Sends the message to the customer by email when you click **Send as Email**. |
| Sales agent | **Save as internal note** | Saves a note only sales agents can see when you click **Save Note**. Internal notes are highlighted in yellow and never shown to the customer. |

## What the timeline shows

The timeline records these entries. Each one shows who made it (for example "Customer" or "Sales Team") and when.

| Entry | What it records |
| --- | --- |
| **Order actions** | The order being created, updated, approved or changing status. |
| **Customer messages** | Messages the customer sends from the order. |
| **Sales agent messages** | Messages from the assigned sales agent or your team. |
| **Internal notes** | Notes saved by sales agents, hidden from the customer. |
| **Order edits** | An audit record of changes such as quantities, prices or items. |
| **Payments** | Payments made against the order. See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md). |

## Choose who's notified about new messages

When a customer posts a message on an order that has no sales agent assigned, SparkLayer emails the addresses you choose here.

1. Go to **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app.
2. Next to **Purchase notifications**, click **Edit**. Until you add someone, it says "No one is emailed when quotes and orders update."
3. Under **Email addresses**, enter the addresses to notify. Separate addresses with commas.
4. Click **Save**.

**Purchase notifications** decides "Who gets an email when a quote or order updates and nobody is assigned to it." Quotes use the same setting: see [Quote notifications](https://docs.sparklayer.io/help/ordering/quoting.md).

## Emails the timeline sends

Only new messages send emails. Other order activity and internal notes don't.

| Email | Sent to | When |
| --- | --- | --- |
| **Buyer message** | The assigned sales agent if there is one, any notification addresses you've added, or a fallback store inbox (your store's email under **Store details**, see [Settings](https://docs.sparklayer.io/help/dashboard/settings.md)) | The customer posts a message on an order. |
| **Sales Agent message** | The customer | A sales agent posts a message on an order. |

The email shows the message and a **Reply to message** button that opens the order. You can also send customers and agents straight to an order's details with a link: see [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md).

To change what the emails say, go to **Settings > Templates** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/theme)), or **SparkLayer Wholesale > Settings > Templates** in the Shopify app. See [Templates](https://docs.sparklayer.io/help/dashboard/settings.md).

### Replies by email

When someone replies to a notification email, the reply is added to the order's timeline as a message. It shows the sender's name and email address, and both the customer and your sales team can see it. If the email thread has several replies, only the most recent is added. Images and attachments are removed. 

### Send emails from your own domain

By default, emails are sent from `no-reply@mail.sparklayer.io`. On the Pro and Enterprise plans, you can send them from your own address, such as `store@mail.yourstore.com`. They then match your brand and are more likely to be delivered.

1. Go to **Settings > Configurations > Store** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Store** in the Shopify app and click **Edit** next to **Custom email domain**.
2. Tick **Use my own domain for SparkLayer emails** ("Emails to and from customers use your domain. Our team helps you verify it.").
3. Enter the **Email user** (the part before the @) and your **Domain**, then click **Save**. Our team then helps you verify the domain.

This only changes emails sent by SparkLayer, not emails from your eCommerce platform or other systems.

## FAQs

**Which plans include Timeline and communications?**

All SparkLayer plans. Sending emails from your own domain needs the Pro or Enterprise plan.

**Do I need the Quoting Engine to use the timeline?**

No. You can turn on the timeline without the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md).

**Can I turn off the timeline for some customer groups?**

No. Once it's turned on, the timeline appears on all supported order types for all customers.

**Does other order activity send notifications?**

No. Only new messages send emails.

**Are internal notes visible to customers?**

No. Internal notes are only visible to sales agents, and they don't send an email.

**Does this replace Shopify order notes?**

**Shopify only:**

No. Shopify order notes don't change. The timeline adds a record inside SparkLayer.

## Feedback

Tell us what you think of Timeline and communications at [product@sparklayer.io](mailto:product@sparklayer.io).


---

# Ordering & checkout

URL: https://docs.sparklayer.io/help/ordering

Configure how B2B customers build carts, check out, pay and reorder in SparkLayer, from payment methods and net terms to quoting, shipping rules and invoices.

> **Quick summary**
>
> - This section covers the B2B ordering journey, from the cart to the order in your eCommerce platform: checkout fields, payment, credit and net terms, tax and shipping, quotes, invoices and reordering tools.
> - Customers order in the SparkLayer [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) on your storefront, and each order is created in your eCommerce platform.
> - Most features are on every plan, including net terms and Pay on Account. Intelligent Cart and SparkLayer shipping rates need Starter, Invoices need Growth and Quotes need Pro (or the Quoting Engine add-on on Starter and Growth). See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
> - Switch ordering features on at **Settings > Configurations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations** in the Shopify app, and set up the checkout at **Storefront > Options > Checkout** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Checkout** in the Shopify app.

## How B2B ordering works

The B2B ordering journey:

1. **Cart**: The customer adds products, from search, shopping lists, Favourites or Intelligent Cart.
2. **Checkout**: They choose a shipping address, fill in checkout fields such as a PO number, and pick a shipping method.
3. **Payment**: They pay upfront by card, by invoice or on account, or request a quote.
4. **Order in your platform**: The order is created in your eCommerce platform as a draft or completed order, and shows in Orders.

Tax is added at the last step of the checkout, from your platform's tax settings. Shipping costs come from your platform or SparkLayer shipping rates.

## Where the settings live

| Screen | What you set there |
| --- | --- |
| **Settings > Configurations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations** in the Shopify app | Feature switches in four cards: **Ordering** (company users, company locations, multi-location stock, recurring orders, payments visibility), **Quotes and invoices**, **Pricing and cart** and **Store** (store details, email domain, purchase ID prefix). |
| **Storefront > Options > Checkout** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Checkout** in the Shopify app | Checkout fields, the order of payment methods, saving addresses and hiding the AI cart features. |
| **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app | Which payment methods, order limits and checkout access each group of customers gets. |
| **Settings > Shipping** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping** in the Shopify app | SparkLayer's own B2B shipping methods, and which Shopify method is pre-selected at checkout. |
| **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app | On Shopify, whether draft orders are completed automatically. |

## Checkout and payment

- [Cart & checkout](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md): How the SparkLayer cart and checkout work for B2B customers, and the settings that change them.
- [Checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md): Collect extra information at checkout, such as a PO number, with custom and standard checkout fields.
- [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md): Choose which B2B payment methods customers see, rename and reorder them, and set the default.
- [Credit, net terms & invoicing](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md): Set credit limits, account balances and payment terms such as Net 30 or Net 60 for B2B customers.
- [Invoices](https://docs.sparklayer.io/help/ordering/invoices.md): Let B2B customers download PDF invoices from My Account, and customise what they show.
- [Set up quotes](https://docs.sparklayer.io/help/ordering/quoting.md): Let customers request quotes, then edit, negotiate and convert them into orders.

## Tax and shipping

- [How tax works at checkout](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md): How SparkLayer shows net prices and adds tax at checkout, and how to set up tax on your platform.
- [Shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md): Use your store's shipping rates, or set up B2B shipping methods priced by order total or weight for each customer group.

## Reordering tools

- [Quick Order](https://docs.sparklayer.io/help/sales-ordering/catalog.md): Let customers browse your range in pictures and add products to the cart, with pack sizes and volume breaks applied.
- [Shopping lists](https://docs.sparklayer.io/help/ordering/shopping-lists.md): Let customers save named lists of products and quantities, and add a whole list to the cart.
- [Favourites](https://docs.sparklayer.io/help/ordering/favourites.md): Let customers save products with a heart icon and add them to the cart from My Account.
- [Intelligent Cart (AI)](https://docs.sparklayer.io/help/ordering/intelligent-cart.md): Fill the cart by uploading a PDF, spreadsheet or photo, forwarding an email or scanning barcodes.

## After the order

- [Complete draft orders automatically](https://docs.sparklayer.io/help/ordering/automation-and-workflows.md): On Shopify, complete draft orders automatically, and get email alerts for new draft orders.
- [Orders](https://docs.sparklayer.io/help/dashboard/orders.md): Track B2B orders in SparkLayer, with sales for a period compared with the period before, and your sales history.


---

# Cart and checkout

URL: https://docs.sparklayer.io/help/ordering/cart-and-checkout

How the SparkLayer checkout works, step by step, and how to customise it: the PO number field, payment and checkout messages, terms link and order limits.

> **Quick summary**
>
> - B2B customers check out in the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) in four steps: **Cart**, **Details**, **Review & Pay** and **Complete**. Customers who can request quotes also see **Request Quote**.
> - Set order limits per customer group at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app. Set checkout fields, the order of payment methods and saving addresses at **Storefront > Options > Checkout** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Checkout** in the Shopify app.
> - Change most checkout text without code at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app, including payment and checkout messages, the terms link and the order complete message.

## How it works

The four steps of the SparkLayer checkout:

1. **Cart**: Check the lines, apply discount codes, then click **Checkout**
2. **Details**: Shipping address, PO number, files and a preferred shipping date
3. **Review & Pay**: Shipping method, payment method, order summary and terms
4. **Complete**: The order is placed and sent to your eCommerce platform

A strip at the top of My Cart shows the four steps. Finished steps get a tick, and customers can click one to go back. From **Details** onwards, a bar at the bottom shows the sub-total, with a **Back** button beside the main button.

You change the checkout in one of three ways:

| What you're changing | How | Who does it |
| --- | --- | --- |
| Text customers see | A translation key, at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app or in `translations` in your Core Script. See [Change checkout text](#change-checkout-text). | You, in SparkLayer. No code needed. |
| How something behaves | A display setting in your [Core Script](https://docs.sparklayer.io/help/glossary.md#core-script) (the SparkLayer code in your theme), such as `display: { customerReferenceRequired: true }`. See [Frontend integration](https://docs.sparklayer.io/developers/frontend.md). | Your developer or agency |
| How something looks | CSS variables in your [CSS overrides](https://docs.sparklayer.io/help/storefront/customising-design.md). | Your developer, agency or anyone who edits your theme code |

## The checkout, step by step

### Cart

The customer checks their lines, quantities, **Discounts & codes** and **Sub-total**, then clicks **Checkout**.

**More detail**

If the order breaks the customer group's [order limits](#set-minimum-and-maximum-order-values), My Cart shows a message and the customer can't check out until they change it. If their group can request quotes, **Request Quote** sits beside **Checkout**: see [Submit a quote instead](#submit-a-quote-instead).

### Details

The customer confirms the delivery address, fills in your [checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md), such as a PO number, and clicks **Continue**. You choose which fields appear, their names and their order.

**What's on the Details step**

| Part | What it does |
| --- | --- |
| **Shipping Address** | Lists the customer's saved addresses (as a drop-down list if there are more than 4), with **Add a new address**. A note says they can edit addresses from their account. |
| **Purchase Order (PO) Number** | A box for the customer's PO number, if you've turned on the PO number field. |
| **Upload Files** | Attaches files to the order, such as a purchase order, if you've turned on file uploads (Growth plan and above). |
| **Preferred Shipping Date** | The date the customer would like the order shipped, if you've added a shipping date field. It can open on the earliest date you allow. |
| **Additional Information** | A free-text box for notes, if it's turned on. See [Set up the Additional Information field](#set-up-the-additional-information-field-po-number). |
| Other checkout fields | Any other fields you've added, such as delivery instructions or a tick box. |

Addresses come from the customer's address book in your store admin. With [company locations](https://docs.sparklayer.io/help/customers/company-locations.md), the address is the location's own, with a note saying so and a **Change location** link.

When adding a new address, the customer can also tick:

| Option | What it does |
| --- | --- |
| **Set as default shipping address** | Uses this address for shipping on future orders. |
| **Set as default billing address** | Uses this address for billing on future orders. |
| **Save address to address book** | Saves the address so it can be edited later in the [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md). |

They then click **Continue and use this address**. To stop customers adding or editing addresses, see [Allow customers to edit addresses](https://docs.sparklayer.io/help/customers/customer-groups.md#allow-customers-to-edit-addresses).

### Review & Pay

The customer chooses a shipping and payment method, checks the totals, ticks the terms and clicks **Complete Order**, which shows the total (for example, **Complete Order: $1,540.03**). Tax and shipping are worked out on this step: see [Tax and shipping](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md).

**What's on the Review & Pay step**

| Part | What it does |
| --- | --- |
| Checkout message | Your own message in a box at the top, if you've [added one](#add-a-checkout-message). |
| **Shipping Method** | The shipping options, each with its cost, such as standard or express. See [Shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md). |
| **Payment Method** | The [payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md) the customer's group allows, such as **Pay on Account**, **Pay by Invoice** and **Pay Online by Card**, with a message about the selected method. |
| **Order Summary** | **Discounts & codes**, **Sub-total**, **Shipping** (with the delivery address), **Tax** and **Total**. With [company locations](https://docs.sparklayer.io/help/customers/company-locations.md), an **Ordering for** row names the location, with **Change**. |
| Terms tick box | "I agree to the terms and conditions". See [Change the terms and conditions link](#change-the-terms-and-conditions-link). |
| **Complete Order** | Places the order. The button shows the total, for example **Complete Order: $1,540.03**. |

### Complete

The customer sees **Thank you for your order!**, with a note that a confirmation email is on its way and they can track the order in My Account. **View order** opens it in [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md).

The order goes to your eCommerce platform like any other, as a draft or completed order depending on the payment method. See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md).

### Submit a quote instead

If the customer's group can request quotes with the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md), they can send the cart to your team as a quote instead of placing an order. No payment is taken.

1. In **My Cart**, click **Request Quote**, next to **Checkout**. Sales agents ordering for a customer see **Submit Quote** instead.
2. On **Details**, choose the address and fill in the fields.
3. On **Review & Pay**, a banner says **This order will be submitted as a quote**. Choose a **Shipping Method** and check the **Order Summary**. There's no payment method: the customer chooses one when they complete the quote.
4. Fill in **Quote Details**, tick the terms and conditions and click **Submit Quote**, which shows the total (for example, **Submit Quote: $1,540.03**).

The Complete step says **Thank you for requesting a quote!** Your team is emailed, and the quote appears in the customer's My Account. For what happens next, see [Work on a quote](https://docs.sparklayer.io/help/ordering/work-on-a-quote.md).

## Set minimum and maximum order values

Order limits stop a customer checking out until the order meets your rules, such as a $100 minimum spend or at least 50 items. You set them for each customer group, as **Order total limits** or **Order quantity limits**: see [Set order limits](https://docs.sparklayer.io/help/storefront/quantity-rules.md#order-limit-rules).

Order totals exclude tax, unless you show [tax-inclusive prices](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-tax-inclusive-prices). Until the order meets the limit, My Cart shows a message and the customer can't check out. For every option and the message text, see [Order limits in customer groups](https://docs.sparklayer.io/help/storefront/quantity-rules.md#order-limit-rules).

## Offer discounts and coupon codes

Customers enter a coupon code with **Discounts & codes**, in the cart or in the **Order Summary**, and discounts can also apply automatically. For what customers see, see [Discounts and promotions](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md#discounts-and-promotions) in My Cart.

B2B discounts need the Growth plan or above. To set them up, including order-level, percentage, fixed, scheduled and customer group discounts, see [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md).

## Change checkout text

Every piece of text in the cart and checkout has a translation key, such as `cart.checkout.notes.label`. Change any of it without code:

1. Go to **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app and open **Translation overrides**.
2. Click **Add override**.
3. Choose the language, such as `en`, and the key, then enter your text.
4. Click **Save and publish**.

The sections below give the key for each message, plus Core Script code for developers. To find other keys, see [Find the key for a piece of text](https://docs.sparklayer.io/help/storefront/languages-and-international.md#find-the-key-for-a-piece-of-text) and [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md).

## Add a checkout message

A checkout message sits in a box at the top of **Review & Pay**, above the shipping methods. Use it for anything customers need to know before ordering, such as shipping cut-off times or payment information.

To add one, set the key `cart.checkout.review-step.custom-message` in **Translation overrides** (see [Change checkout text](#change-checkout-text)). The message shows to all customers; you can't vary it by customer.

**Core Script code for your developer**

```javascript title="Core Script"
translations: {
  en: {
    "cart.checkout.review-step.custom-message": "Add your custom checkout message here",
  }
},  
```

### Style the checkout message

The message's colours, spacing, alignment and border are CSS variables in your website's CSS. See [Customising design](https://docs.sparklayer.io/help/storefront/customising-design.md).

**CSS for your developer**

This is a theme code change, so pass it to your developer if you don't edit your theme:

```html
<style>
:root {
  --spark-message-checkout-review-message-color: #555;
  --spark-message-checkout-review-message-background: #fff;
  --spark-message-checkout-review-message-padding: 0.5em 0.75em;
  --spark-message-checkout-review-message-alignment: left;
  --spark-message-checkout-review-message-border: 1px solid #CCCCCC;
}
</style>
```

## Add a message for each payment method

A payment method message sits under the payment methods on **Review & Pay** and explains the selected method. For example, tell customers who choose **Pay by Invoice** when and how you'll invoice them. It changes as the customer picks a method.

Set the method's key in **Translation overrides** (see [Change checkout text](#change-checkout-text)):

| Payment method | Key |
| --- | --- |
| **Pay by Invoice** | `cart.checkout.payment-providers.paymentByInvoice.message` |
| **Pay Online by Card** | `cart.checkout.payment-providers.upfrontPayment.message` |
| **Pay on Account** | `cart.checkout.payment-providers.paymentOnAccount.message` |
| **Request for Quote** | `cart.checkout.payment-providers.quote.message` |

Each message shows to every customer who selects that method; you can't vary it by customer. To choose which methods each customer sees, see [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md). A message is a good place to explain a [payment method rule](https://docs.sparklayer.io/help/ordering/payment-method-rules.md)'s discount or surcharge. For the keys of the rule's own text, see [Change the text customers see](https://docs.sparklayer.io/help/ordering/payment-method-rules.md#change-the-text-customers-see).

**Core Script code for your developer**

```javascript title="Core Script"
translations: {
  en: {
    "cart.checkout.payment-providers.paymentByInvoice.message": "This is a message for Payment by Invoice",
    "cart.checkout.payment-providers.upfrontPayment.message": "This is a message for Pay Online by Card",
    "cart.checkout.payment-providers.paymentOnAccount.message": "This is a message for Pay on Account",
    "cart.checkout.payment-providers.quote.message": "This is a message for Request for Quote",
  }
},  
```

## Set up the Additional Information field (PO number)

**Additional Information** is a free-text box on the **Details** step, up to 512 characters. Customers often use it for a PO number, delivery instructions or other notes. Its placeholder is "Order notes e.g. PO Number".

On Shopify, the text appears in the order's **Notes** section. You can also send it to a backend system with the [SparkLayer API](https://docs.sparklayer.io/developers/api.md). For other platforms, see the [developer docs](https://docs.sparklayer.io/developers.md).

To store a PO number or customer reference in a structured, searchable place, use the standard **PO Number** or **Customer Reference** checkout field instead. Add them without code at **Storefront > Options > Checkout** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Checkout** in the Shopify app: see [Move to the standard fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md#move-to-the-standard-fields).

You can change the field's text yourself. Making it required, limiting its length or hiding it are Core Script settings for your developer.

### Change the label and helper text

Set these keys in **Translation overrides** (see [Change checkout text](#change-checkout-text)):

| Key | Default text |
| --- | --- |
| `cart.checkout.notes.label` | Additional Information |
| `cart.checkout.notes.placeholder` | Order notes e.g. PO Number |
| `cart.checkout.notes.helper-text` | Please note, this is required before placing your order (only shown if the field is required) |
| `cart.checkout.notes.default-helper-text` | Empty. Add a helper message to show below the field. |

**Core Script code for your developer**

```javascript title="Core Script"
translations: {
  en: {
    "cart.checkout.notes.label": "Additional Information",
    "cart.checkout.notes.placeholder": "Order notes e.g. PO Number",
    "cart.checkout.notes.helper-text": "Please note, this is required before placing your order", /* Only shown if the field is set to required */
    "cart.checkout.notes.default-helper-text": "", /* Add a helper message below the form field */

  }
},  
```

### Make the field required

Your developer adds this to the `display` object in your Core Script. Customers then can't place an order until they fill in the field, and see the helper text "Please note, this is required before placing your order".

```javascript title="Core Script"
display: {
  customerReferenceRequired: true,
},
```

### Limit the number of characters

Your developer can set a limit lower than 512:

```javascript title="Core Script"
display: {
  customerReferenceMaxLength: 512, /* update 512 as required */
},
```

### Hide the field

Your developer adds this to the Core Script:

```javascript title="Core Script"
display: {
  customerReferenceHidden: true,
},
```

## Change the terms and conditions link

Customers tick "I agree to the terms and conditions" before they complete the order. The link goes to `policies/terms-of-service` by default.

| To change | How | Who does it |
| --- | --- | --- |
| The words around the link | The keys `cart.checkout.terms.start` ("I agree to the "), `cart.checkout.terms.link` ("terms and conditions") and `cart.checkout.terms.end`, in **Translation overrides** (see [Change checkout text](#change-checkout-text)) | You, in SparkLayer |
| Where the link goes | `termsAndConditionsLink` in your Core Script. On Shopify, it can change with the customer's tags or the store language. | Your developer |

**Core Script code for your developer**

Set the link:

```javascript title="Core Script"
termsAndConditionsLink: "/policies/terms-of-service",
```

**Shopify only:**

On Shopify, use Liquid to show a different link by customer tag or store language:

```javascript title="Core Script"
{% if customer.tags contains 'b2b' %}
  termsAndConditionsLink: '/policies/b2b-terms',
{% elsif customer.tags contains 'b2b-2' %}
  termsAndConditionsLink: '/policies/b2b-2-terms',
{% elsif shop.locale == "fr" %}
  termsAndConditionsLink: '/policies/fr-terms-and-conditions',
{% else %}
  termsAndConditionsLink: '/policies/terms-and-conditions',
{% endif %}
```

To switch the link by language only:

```javascript title="Core Script"
{%- if shop.locale == "fr" -%}
  termsAndConditionsLink: '/policies/fr-terms-and-conditions',
{%- else -%}
  termsAndConditionsLink: '/policies/terms-and-conditions',
{%- endif -%}
```

To change the wording in the Core Script instead of Translation overrides:

```javascript title="Core Script"
translations: {
  en: {
    "cart.checkout.terms.start": "I agree to the ",
    "cart.checkout.terms.link": "terms and conditions",
    "cart.checkout.terms.end": " ",
  }
}, 
```

## Change the tax and shipping note

A short note under the main button tells customers when tax and shipping are calculated. Set these keys in **Translation overrides** (see [Change checkout text](#change-checkout-text)): 

| Where | Default text | Key |
| --- | --- | --- |
| Under **Checkout** on the **Cart** step | Tax and shipping costs calculated during checkout | `cart.tax-shipping-note` |
| Under **Continue** on the **Details** step | Tax and shipping costs shown on next step | `cart.tax-shipping-message` |

**Core Script code for your developer**

```javascript title="Core Script"
translations: {
  en: {
    "cart.tax-shipping-note": "Tax and shipping costs calculated during checkout",
    "cart.tax-shipping-message": "Tax and shipping costs shown on next step",
  }
}, 
```

For how tax and shipping are calculated, see [Tax and shipping](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md).

## Change the order complete message

After placing an order, customers see a heading and a short message, with a separate version for quote requests. Set these keys in **Translation overrides** (see [Change checkout text](#change-checkout-text)). `{email}` is replaced with the customer's email address.

| Key | Default text |
| --- | --- |
| `cart.thanks.payment.main` | Thank you for your order! |
| `cart.thanks.payment.blurb` | Your order has now been placed and you will shortly receive email confirmation to `{email}`. You can check the status of your order at any time by going to 'My Account'. |
| `cart.thanks.quote.main` | Thank you for requesting a quote! |
| `cart.thanks.quote.blurb` | We can confirm that your request for a quote has been received and we'll be in touch once our team has reviewed it. |

**Core Script code for your developer**

```javascript title="Core Script"
translations: {
  en: {
    "cart.thanks.payment.main": "Thank you for your order!",
    "cart.thanks.payment.blurb": "Your order has now been placed and you will shortly receive email confirmation to {email}. You can check the status of your order at any time by going to 'My Account'.",
    "cart.thanks.quote.main": "Thank you for requesting a quote!",
    "cart.thanks.quote.blurb": "We can confirm that your request for a quote has been received and we'll be in touch once our team has reviewed it.",
  }
},
```

## More ways to change the cart

### Collect a tax ID

Some countries require a customer's tax ID (or equivalent) at checkout, so orders comply with local tax law and avoid customs delays or fines. See [Collect a tax ID for international shipping](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md#collect-a-tax-id-for-international-shipping).

### Add your own content with slots

Custom slots (also called targets) add your own HTML in set places in My Cart, such as above the cart lines (**My Cart** slot) or under the thank-you message on **Complete** (**Order complete** slot). Add them at **Storefront > Options > Custom slots** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Custom slots** in the Shopify app. See [Custom slots](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md).

### Hide the RRP in the cart

If you show an [RRP (MSRP)](https://docs.sparklayer.io/help/pricing/pricing-display.md), the cart shows it under each line's price, such as "RRP: US$5.99". To hide it, add this to your [CSS overrides](https://docs.sparklayer.io/help/storefront/customising-design.md) (a theme code change):

```css
--spark-cart-rrp-display: none;
```

### Change how product images fit in the cart

Product images that aren't square may be cropped in the cart. Add one of these to your [CSS overrides](https://docs.sparklayer.io/help/storefront/customising-design.md) (a theme code change):

```css
--spark-cart-background-size: cover /* Set image to fill the space*/
--spark-cart-background-size: contain /* Set image to be fully visible*/
```

## Related features

| Feature | Where to read about it |
| --- | --- |
| Searching for products and adding them by SKU in the cart | [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) |
| Which payment methods customers see, and their names and order | [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md) |
| Custom fields, standard fields and file uploads at checkout | [Checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md) |
| Shipping methods and rates | [Shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md) |

## FAQs

**Where have custom checkout fields and file uploads gone?**

They have their own page: [Checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md). For file uploads, see [Let customers upload files at checkout](https://docs.sparklayer.io/help/ordering/checkout-fields.md#file-upload-file-attachments).

**Can I show a different payment or checkout message to different customers?**

No. Both show to all customers, though payment messages change with the payment method the customer selects.

**Can I change the checkout text without editing code?**

Yes, at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app. See [Change checkout text](#change-checkout-text).


---

# Catalog and Quick Order

URL: https://docs.sparklayer.io/help/sales-ordering/catalog

Browse your whole range in pictures and add products straight to the order: grid, quick-buy list or matrix views, search, filters and pack-aware quantities.

> **Catalog and Quick Order is in early access.** Request it for your store. [Request early access](https://feedback.sparklayer.io/get-started?choice=now).

> **Quick summary**
>
> - Catalog and Quick Order is an image-first product browser inside the SparkLayer widget. It has search, a collection filter, 3 views, and quantities that follow your pack sizes and volume breaks.
> - Sales reps see it as the **Catalog** tab. Customers see the same browser as the **Quick Order** tab, so it's a fast way for anyone to build an order.
> - Every **Add** goes straight into the cart. For a rep, that's the cart of the customer they're [ordering for](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md), at that customer's prices.
> - The order button at the top, such as **60 in order**, shows what's in the order so far without leaving the catalog, and **Review order** opens the cart to check out. Catalog and Quick Order need the Starter plan or above.
> - To keep products out of the catalog, such as custom products or fees, hide them for every B2B customer or for some customer groups. See [Hide products from the catalog](#hide-products).

## How it works

Catalog and Quick Order show your products as a page of cards, each with its photo, price, stock and quantity rules. Choose a quantity and click **Add**. The line goes into the order as if it had been typed into [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md). The order stays in the cart, so you can switch between browsing and the cart at any time.

Building an order from the catalog:

1. **Find products**: Search, filter by collection or sort the range
2. **Set a quantity**: Choose the variant and quantity; packs and volume prices apply
3. **Add**: The line goes straight into the cart
4. **Review order**: Open the cart from the running order and check out

| Who | Tab name | Adds go to |
| --- | --- | --- |
| Customer | **Quick Order** | Their own cart |
| Sales rep | **Catalog** | The cart of the customer they're ordering for |

## Open the catalog

1. Open the SparkLayer widget in your store, for example from the cart or account link.
2. Sales reps: choose the customer you're ordering for first. See [Choose a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#choose-a-customer).
3. Click **Quick Order** (customers) or **Catalog** (sales reps). It's the last tab, after **My Account**.

**More detail**

The widget widens while the tab is open, so more products fit on the screen. The rep's **Catalog** header also has a **Counter** button, which opens [Counter mode](https://docs.sparklayer.io/help/sales-ordering/counter-mode.md) for serving customers in person.

## Choose a view

The catalog has 3 views. Switch between them with the view icons at the top of the catalog. Your choice is remembered next time.

| View | Best for | What you see |
| --- | --- | --- |
| **Grid view** | Browsing by eye, new products, customers who know a product by its look | A card per product: photo, collection, name, SKU, price and MSRP, volume offer, stock and pack rules, then the option, quantity, **Add** and the heart |
| **Quick-buy list** | Fast ordering when you know what you want | A table with **Product**, **Variant**, **Qty** and **Line total** columns, and **Add** on each row. The line total also shows the quantity times the unit price |
| **Matrix ordering** | Products with two options, such as colour and size | Each two-option product as a grid of every combination, so you can fill in several at once. Other products show as a single row |

**More detail**

On a narrow screen the list's columns stack, with **Variant**, **Qty** and **Line total** labelled on each row. On a narrow grid card, the **Add** button shows only the plus sign and the line total, so the price is never cut off.

## Set the quantity

Each product starts at its smallest allowed quantity. The quantity follows your [quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md):

- **−** and **+** move by one pack. For a product sold in packs of 12, they go 12, 24, 36.
- You can type any number. When you leave the box, it snaps to the nearest pack and stays within the minimum and maximum.
- The rules show under the price, such as **Min 6 · Packs of 6** or **Max 100**.

For a product with options, choose the variant from the dropdown first. The price, stock and volume offer change to match it.

### Volume breaks

If a product has [quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md) (volume breaks), its card shows the best offer in words, such as "From $7.70 for 34+", or "$6.40 each by the pack" for a product sold in packs.

1. Hover over, focus or tap the offer to see **Qty discount pricing**: every break with its **Qty**, **Price** and **Savings**.
2. Click a row to set the quantity to that break.

When the quantity reaches a break, the card shows the saving (for example **−20%**) and **Add** shows the discounted line total. The cart uses the same price.

### Stock

| Status | Means |
| --- | --- |
| **In stock** | Available, with a count (such as **100+**) if you [show unit counts](https://docs.sparklayer.io/help/storefront/stock-display.md). |
| **Low** | Stock is low, with the units left if counts are shown. |
| **Pre-order** | Can be ordered now and ships later, with the expected date. |
| **Out of stock** | Can't be ordered: the button reads **Sold out**. You can still add it to the wishlist. |

What customers see depends on the [stock display](https://docs.sparklayer.io/help/customers/customer-groups.md#show-stock-levels) settings of their customer group.

## Add products to the order

1. Choose the variant and quantity.
2. Click **Add**. It turns green with a tick, and a message confirms who the order is for.

**More detail**

The product's card then shows a tick and the quantity already in the order, and the list view shows how many are in the order, such as **12 in order**, under the button. These counts are read from the cart, so they're always up to date. If a product is already in the order, **Add** adds to the quantity that's there.

### Add from the matrix

1. In **Matrix ordering**, type a quantity into each combination you want. Each cell shows its stock and price, and **Unavailable** for combinations you can't order.
2. Check the total under the grid: units selected and the order value.
3. Click **Add to order** to add every combination at once.

**More detail**

In the matrix, volume breaks count the whole grid's quantity, so 6 small and 6 medium count as 12. Click the info icon in a cell to see that variant's SKU and its pack rules.

### Add to a customer's order as a sales rep

When a rep is [ordering for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md), every **Add** goes into that customer's cart, at that customer's prices, stock and quantity rules. The confirmation names the customer, so you always know whose order you're building. To build an order for someone else, [switch customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md) first.

## Review the order

1. Click the order button at the top right. It shows how many units are in the order, such as **60 in order**. The **In this order** panel shows the last 3 lines added, with the number of lines and units.
2. To see every line, click the link under them, such as **+ 4 more lines in the cart**. Click **Show fewer lines** to go back.
3. Click **Keep browsing** to carry on, or **Review order** to open the cart and [check out](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md#check-out).

## Add to the wishlist

To save a product for later, click the heart beside its **Add** button (**Add to wishlist**). The heart fills when the product is saved. Click it again to remove it. You can save a product that's out of stock.

**More detail**

The wishlist belongs to the customer's account: a rep ordering for a customer saves to that customer's wishlist, not their own. Saved products appear in the customer's [Favourites](https://docs.sparklayer.io/help/ordering/favourites.md) in My Account.

## Share a view

To send someone what you're looking at, click **Copy link**. It copies the search, collection, sort, page and view. Paste it into an email or chat, and the person who opens it lands on the same view. 

## Hide products from the catalog

Some products shouldn't be ordered straight from the catalog: a custom product that needs artwork uploaded, or a printing charge or add-on fee that only belongs on an order with something else. Hide them with the `sparklayer.settings` [metafield](https://docs.sparklayer.io/help/glossary.md#metafields) on each variant, for every B2B customer or only for some customer groups.

| You want | Set on each variant | What customers and reps see |
| --- | --- | --- |
| **Hide it** | `"display": false, "sell": false` | Nothing: it's left out of Catalog and Quick Order, search in My Cart and SparkLayer's other views |
| **Show it, but stop orders** | `"sell": false` | The product, marked **Unavailable for this account**, with no way to add it |
| **Hide it from some customer groups** | An entry for each of those groups | Hidden only for customers in those groups |
| **Show it to some customer groups only** | A `base` entry that hides it, and an entry for each group that sees it | Hidden for everyone else |

Sales reps see what the customer they're ordering for sees, so a product hidden from a customer's group is hidden from the rep's **Catalog** too.

### Step 1. Turn on the metafield in SparkLayer

You only do this once. 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 and, in the **Metafields** card, click **Configure** next to **SparkLayer metafields**, then enable the product settings metafield. See [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md#set-product-settings-for-a-customer-group).

### Step 2. Build the value

Choose who shouldn't see the products and whether to hide them or only stop orders. The value is the same for every product. For customer groups, use each group's handle, such as `trade`: find it by clicking the group's name at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app.

For example, this value hides a variant from every B2B customer:

```json
[{ "customer_group": "base", "display": false, "sell": false }]
```

### Step 3. Add it to each variant

The value goes on every variant you're hiding: a product with 3 sizes needs it on all 3.

- **A few products:** open each variant in your store's admin, paste the value into its `sparklayer.settings` field and save. In Shopify, it's **Settings** under **Metafields**, as the form shows.
- **Many products:** fill in the field for every variant in one table.
- **With your AI assistant:** connect your Shopify store to it, such as with the Shopify connector in Claude, click **Ask Claude** or **Ask ChatGPT** in the form above, and tell it which products. The assistant finds every variant, shows you each change and waits for your approval before saving anything.

**Lots of products? Fill them in one table (Shopify):** in your Shopify admin, go to **Products**, tick the products and click **Edit products**. Click **Columns**, tick the SparkLayer field under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

**More detail**

A variant can already have a `sparklayer.settings` value, such as a pack size for a customer group. Pasting a new value replaces it. Add the `display` and `sell` keys to the entries that are there instead, or let the AI assistant merge them for you: its prompt keeps every other setting.

### Step 4. Check it worked

Changes take about 10 minutes to sync. Then sign in as a customer in one of the groups, or [order for one](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md) as a rep, open **Quick Order** or **Catalog** and search for the product.

`display` and `sell` only change SparkLayer. To hide products from your store's own pages too, such as from retail shoppers, see [Hide products from customers](https://docs.sparklayer.io/help/guides/hide-products.md).

## The parts of the screen

| Part | What it shows / does |
| --- | --- |
| View switch | Three icons: **Grid view**, **Quick-buy list** and **Matrix ordering**. Your choice is remembered next time. |
| Order button, such as **60 in order** | How many units are in the order. Click it to see the order's lines (see [Review the order](#review-the-order)). |
| Collection filter | **All collections**, or one collection, with a count of products in each. Type in **Filter collections…** to find one in a long list. On Shopify, the collections follow your navigation menu: see [Collections in Catalog and Quick Order](https://docs.sparklayer.io/help/platforms/shopify/catalog-collections.md). |
| Search | **Search the catalog…** finds products by name, SKU and collection. With several words, a product must match all of them. |
| Sort | **Name A–Z**, **Price: low to high** or **Price: high to low**. |
| **Copy link** | Copies a link to the view you're looking at (see [Share a view](#share-a-view)). |
| Page footer | The products shown out of the total, with **Prev** and **Next**. Each page holds 24 products. |

If nothing matches, the catalog says **No products match** and suggests trying a different search or collection.

## FAQs

**Is Quick Order different from the Catalog?**

No. It's the same product browser. Customers see it as **Quick Order**; sales reps see it as **Catalog**, with a **Counter** button for [Counter mode](https://docs.sparklayer.io/help/sales-ordering/counter-mode.md).

**Why did my quantity change after I typed it?**

The product is sold in packs or has a minimum or maximum. When you leave the box, the quantity snaps to the nearest pack within those limits. See [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md).

**Why is a price lower than the card's price in the cart?**

The quantity in the order has reached a volume break. The cart prices each line at the break its total quantity reaches, as the catalog does.

**Why can't I find a product?**

Check the collection filter is on **All collections**, and try fewer words: a product has to match every word you search for. The product might also be [hidden](#hide-products) from the customer's group.

**Can I hide every product with a tag, such as CUSTOM?**

Yes, but the setting goes on each variant, not on the tag. Click **Ask Claude** or **Ask ChatGPT** in the [form](#build-the-value) and tell the assistant "every product tagged CUSTOM": it finds and updates them. Or, in your Shopify admin, filter **Products** by the tag, select them all and fill in the field in the bulk editor.

**Can I hide a product from the catalog but still sell it from its product page?**

Not with `display` and `sell`: they apply to every SparkLayer view, including SparkLayer's ordering on the product page. If you need a product orderable only from its product page, [contact support](https://docs.sparklayer.io/help/support.md).


---

# Checkout fields

URL: https://docs.sparklayer.io/help/ordering/checkout-fields

Collect extra details at checkout, such as a PO number, delivery date or file, with standard and custom checkout fields, and see where the data is saved.

> **Quick summary**
>
> - Checkout fields collect extra details on the **Details** step of the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md), such as a PO number, delivery date or delivery instructions.
> - **Standard fields** (**Customer Reference**, **PO Number**, **Requested Shipping Date**) save to set, searchable places on the order. **Custom fields** are your own and save as order notes.
> - Add both without code with **Add field** at **Storefront > Options > Checkout** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Checkout** in the Shopify app. Standard fields need Core Script 4.7.0 or later; custom fields work on any version. File uploads, validation rules and other options need a developer.
> - File uploads need the Growth plan or above. On Wix, a developer adds custom fields in code, with `checkoutCustomElements`.

## How it works

What happens to checkout field data:

1. **Customer fills in the field**: On the Details step of the checkout
2. **Saved with the order**: Standard fields go to set places; custom fields are saved as order notes
3. **Shown to you and the customer**: In your platform's order admin and the customer's My Account
4. **Used elsewhere**: On invoices and packing slips, in automations, or sent to your ERP through the API

| Kind | How it's identified | Where the data goes | Use it for |
| --- | --- | --- | --- |
| **Standard field** | A fixed `id` that SparkLayer recognises | A structured place on the order, such as Shopify's own PO number field. You can search and filter by it, and use it in your theme and template editor. | Customer references, purchase order (PO) numbers and requested shipping dates |
| **Custom field** | A `name` you choose | The order's notes (on Shopify, **Additional details**) | Anything else, such as delivery instructions, a tax ID or a confirmation tick box |

Checkout fields are separate from **Additional Information**, the single free-text box at checkout. See [Cart and checkout](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md#set-up-the-additional-information-field-po-number).

### What you can do without code

| Task | Where | Who does it |
| --- | --- | --- |
| Add the standard fields | **Add field** at **Storefront > Options > Checkout** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Checkout** in the Shopify app (Core Script 4.7.0 or later) | You |
| Add your own custom field | **Add field** at **Storefront > Options > Checkout** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Checkout** in the Shopify app | You |
| Add a file upload field, a validation rule (such as no weekend delivery dates) or any other option | Your [Core Script](https://docs.sparklayer.io/help/glossary.md#core-script), the SparkLayer code in your theme, with `checkoutCustomElements` | Your developer or agency |

## Turn on standard checkout fields

Standard fields need Core Script 4.7.0 or later: check **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.

1. Go to **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app and open **Checkout**.
2. Next to **Checkout fields**, click **Add field** and choose a standard field. Set whether it's shown, optional or hidden.
3. Repeat for each standard field you want.
4. Click **Save and publish**. See [Storefront options](https://docs.sparklayer.io/help/storefront/storefront-options.md).

**Core Script code for your developer**

For more control, a developer can add standard fields to the Core Script by `id`. The `id` must match exactly, or SparkLayer won't recognise the field.

| Field | Field ID |
| --- | --- |
| Customer Reference | `customer-reference` |
| PO Number | `po-number` |
| Requested Shipping Date | `shipping-requested-date` |

```javascript title="Core Script"
checkoutCustomElements: [
  { id: "customer-reference" },
  { id: "shipping-requested-date" },
  { id: "po-number" },
],
```

Standard fields take the same `attributes` and `onChange` keys as custom fields (see [Custom field settings](#custom-field-settings)). For example, to make the customer reference required:

```javascript title="Core Script"
checkoutCustomElements: [
  {
    id: "customer-reference",
    attributes: {
      required: true,
    },
  },
],
```

### Where standard fields appear in your orders

**Shopify only:**

On Shopify, standard fields are saved here:

| Field | Where it's saved |
| --- | --- |
| **PO Number** | Shopify's own PO number field on the order, shown as a **PO number** column in your orders and draft orders lists. |
| **Requested Shipping Date** | A dedicated custom field on the order, shown as `sparkShippingRequestedDate`. |
| **Customer Reference** | The Shopify order notes field. |

Your theme and template editor can use these fields, so you can show them on documents such as [invoices](https://docs.sparklayer.io/help/ordering/invoices.md). Customers see them on the order's **Summary** in [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md).

In the order and activity views, you can:

- Search by Customer Reference
- Search by PO Number
- Filter by Requested Shipping Date, using a date range 

## Add a custom checkout field

A custom field is one you design, such as a delivery instructions box, a tax ID or a confirmation tick box. To add one without code:

1. Go to **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app and open **Checkout**.
2. Next to **Checkout fields**, click **Add field** and fill in the field's details. 
3. Click **Save and publish**.
4. Check the **Details** step of the checkout on your store.

**Shopify only:**

On Shopify, you can show a field only to customers with a particular tag: see [B2B-only content](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-only-content.md).

For validation rules, grouped drop-down menus and every other option, your developer can [add the field in the Core Script](#add-a-custom-field-in-the-core-script-for-developers).

### Where custom field data is saved

Custom field answers are saved to the order as notes.

| Where | What you see |
| --- | --- |
| **Shopify order** | The **Notes** card, under **Additional details**, beside SparkLayer's own details such as `sparkCartId` and `sparkPaymentType`. Shopify calls these **custom attributes**. |
| **Customer's My Account** | The order's **Additional Information**, for example "Preferred Shipping Date: 2024-12-02". |

**Shopify only:**

On Shopify, custom attributes can also:

- Show on packing slips and [email notifications](https://docs.sparklayer.io/help/platforms/shopify/customisations/email-notifications.md)
- Go to a backend system through the [API](https://docs.sparklayer.io/developers/api.md)
- Trigger [Shopify Flow](https://apps.shopify.com/flow) workflows (see our [ready-made Shopify Flow templates](https://docs.sparklayer.io/help/platforms/shopify/customisations/flow.md))

Some third-party invoicing apps can show **Additional details** too; check with the app's developer. To show answers on SparkLayer invoices, see [Content Zones](https://docs.sparklayer.io/help/ordering/invoices.md#add-checkout-field-data-to-an-invoice).

## Let customers upload files at checkout

A file upload field lets B2B customers attach files to the order at checkout, such as a purchase order or order-specific details. It needs the Growth, Pro or Enterprise plan: to change plan, go to **Plan card** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Plan** in the Shopify app or see [SparkLayer plans and pricing](https://www.sparklayer.io/pricing/).

Your developer adds the field in the Core Script:

1. Add the sample below to your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting), inside `checkoutCustomElements`.
2. Change the settings in `attributes` to suit.
3. Edit `translations` to change the text customers see.

**Core Script code and settings for your developer**

```javascript title="Core Script"
checkoutCustomElements: [
	{
		translations: {
			en: {
				title: "File Upload",
				detail: "Files must not be larger than 10MB. You can upload between 1 and 4 files"
			},
		},
		name: "file-upload",
		attributes: {
			type: "file",
			required: false,   // Optional. Default: false
			minlength: 1,     // Optional. Default: 1
			maxlength: 4,     // Optional. Default: 20
			maxsize: '10MB',  // Optional. Default: 20MB, Must be a number followed by `B`, `KB` or `MB`
			fileextensions: [ // Optional. Default: ['txt', 'csv', 'pdf', 'json', 'png', 'jpeg', 'gif', 'webp', 'svg', 'psd', 'xls', 'xlsx', 'ods', 'fods', 'ppt', 'pptx', 'odp', 'fodp', 'doc', 'docx', 'odt', 'fodt']
			  'png',
			  'txt',
			  'pdf',
			  'xls'
			]
		}
	}
],
```

| Setting | What it does |
| --- | --- |
| `required` | Set to `true` to make the customer upload a file. Default: `false`. |
| `minlength` | The **minimum** number of files the customer must upload. For example, `1` means at least 1 file. Default: `1`. |
| `maxlength` | The **maximum** number of files the customer can upload. For example, `4` stops them uploading more than 4. Default: `20`. |
| `maxsize` | The largest file size allowed, as a number followed by `B`, `KB` or `MB` (for example, `10MB`). The default and maximum is 20MB; you can set a lower limit but not a higher one. |
| `fileextensions` | The file types customers can upload. By default, all of these are allowed: `['txt', 'csv', 'pdf', 'json', 'png', 'jpeg', 'gif', 'webp', 'svg', 'psd', 'xls', 'xlsx', 'ods', 'fods', 'ppt', 'pptx', 'odp', 'fodp', 'doc', 'docx', 'odt', 'fodt']` |
| `translations` | The text customers see: the field `title` and the `detail` helper text. |

Customers then see a **File Upload** field on the **Details** step, and their files appear on the order in [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md), under **Attachments**.

**What customers see**

The field has a **Choose file** button and helper text, such as the size limit and number of files allowed. Chosen files are listed above the button, and customers can remove one before continuing.

Under **Attachments**, each file shows its **File name** and **Assignment** (**Order-level** for checkout uploads), with an **Actions** menu to download it.

### Download uploaded files

There are 3 ways to get a file a customer uploaded:

| Who | How |
| --- | --- |
| **The customer** | Signs in and downloads the attachment from the order. |
| **A sales agent** | Signs in on the customer's behalf with [sales agent ordering](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md), opens the order and downloads the attachment. |
| **The API** | The [SparkLayer Files API](https://docs.sparklayer.io/developers/api/files.md) links uploads to the order data, so they can go to a back-office system such as an ERP. For help, contact our [support team](https://docs.sparklayer.io/help/support.md). |

**Shopify only:**

On Shopify, the order lists uploads in **Additional details** under `file-upload` (or your field's `name`). These are file references (`gid://sparklayer/File/...`) that can't be opened from Shopify.

For other platforms, see the [developer docs](https://docs.sparklayer.io/developers.md).

## Let customers upload files on the product page

Line-item uploads let customers attach a file to a specific product, such as a logo or name customisation. This advanced setup needs a developer: see [Let customers upload a file](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#let-customers-upload-a-file) in the JavaScript SDK docs.

How product-level file uploads work once set up:

1. **Product page**: One or more upload fields, each with its own label (such as Front Design) and a Choose file button
2. **Cart**: Each file is shown under the product line, for example Front Design: "logo.png"
3. **My Account**: The files appear on the order under Attachments, assigned to the product's SKU

You can combine product-level and [checkout-level](#file-upload-file-attachments) uploads, such as a logo per product plus a purchase order for the whole order. All files appear on the order in My Account.

## Move to the standard fields

If your developer set up a customer reference or shipping date in the Core Script the older way, switch to the standard fields to get structured storage, search and filtering.

| If your Core Script has | Replace it with |
| --- | --- |
| The **Additional Information** field with `customerReferenceHidden` and `customerReferenceRequired` | The standard field `{ id: "customer-reference" }` |
| A shipping date custom field with a `name`, such as `my-shipping-requested-date` | The standard field `{ id: "shipping-requested-date" }` |

**Before and after code for your developer**

**Customer reference.** If you used the **Additional Information** field with the `customerReferenceHidden` and `customerReferenceRequired` display settings, like this:

```javascript title="Core Script"
display: {
  customerReferenceHidden: false,
  customerReferenceRequired: true,
},
```

replace it with the standard field:

```javascript title="Core Script"
checkoutCustomElements: [
  {
    id: "customer-reference",
    attributes: {
      required: true,
    },
  },
],
```

**Requested shipping date.** If you added a shipping date as a custom field with a `name`, like this:

```javascript title="Core Script"
checkoutCustomElements: [
  { name: "my-shipping-requested-date" },
],
```

switch it to the standard `id`:

```javascript title="Core Script"
checkoutCustomElements: [
  { id: "shipping-requested-date" },
],
```

The `id` must be `shipping-requested-date`. A custom field's `name` can be anything you choose; using the standard `id` is what turns on the structured storage, search and filtering.

## Add a custom field in the Core Script (for developers)

The Core Script gives every option for a custom field, such as validation rules and grouped drop-down menus. It's a theme code change, so pass this section to your developer or agency if you don't edit your theme.

1. Add a `checkoutCustomElements` array to your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting) (or add to it if it's already there).
2. Add one object per field, with a `name`, `translations` (the text customers see) and `attributes` (the field type and validation). See [Custom field settings](#custom-field-settings).
3. Save your theme and check the **Details** step of the checkout.

This example adds a required delivery date field:

```javascript title="Core Script"
checkoutCustomElements: [
  {
    name: "delivery-date",
    translations: {
      en: {
        title: "Delivery Date",
        detail:  "Delivery unavailable on weekends."
      }
    },
    attributes: {
      required: true,
      type: "date"
    }
  },
],
```

One array can hold several fields. This example shows most of the [supported field types](#supported-field-types):

**Example with multiple custom fields**

```javascript title="Core Script"
checkoutCustomElements: [
{
  translations: {
      en: {
          title: "Text field",
          detail: "Explains what the field is for. Must be 2 letters followed by 2-4 digits"
      }
  },
  name: "text-field",
  attributes: {
      required: true,
      type: "text",
      placeholder: "Placeholder shows inside the empty input",
      minlength: 4,
      maxlength: 6,
      pattern: "[a-zA-Z]{2}[0-9]{2,4}"
  }
},
{
  translations: {
      en: {
          title: "Number field",
      }
  },
  name: "number-field",
  attributes: {
      type: "number",
      step: 5,
      min: 15,
      max: 25,
  }
},
{
  translations: {
      en: {
          title: "Date field",
      }
  },
  name: "date-field",
  attributes: {
      type: "date"
  }
},
{
  translations: {
      en: {
          title: "Time field",
      }
  },
  name: "time-field",
  attributes: {
      type: "time"
  }
},
{
  translations: {
      en: {
          title: "Week field",
      }
  },
  name: "week-field",
  attributes: {
      type: "week"
  }
},
{
  translations: {
      en: {
          title: "Datetime field",
      }
  },
  name: "datetime-field",
  attributes: {
      type: "datetime-local"
  }
},
{
  translations: {
      en: {
          title: "Checkbox field",
      }
  },
  name: "checkbox-field",
  attributes: {
      type: "checkbox"
  }
},
{
  translations: {
      en: {
          title: "Month field",
      }
  },
  name: "month-field",
  attributes: {
      type: "month"
  }
},
{
  translations: {
      en: {
          title: "Telephone field",
      }
  },
  name: "telephone-field",
  attributes: {
      type: "tel"
  }
},
{
  translations: {
      en: {
          title: "Email field",
      }
  },
  name: "email-field",
  attributes: {
      type: "email"
  }
},
{
  translations: {
      en: {
          title: "URL field",
      }
  },
  name: "url-field",
  attributes: {
      type: "url"
  }
},
],
```

### Example fields

Copy one of these into your Core Script, or send it to your developer, and adjust it to suit.

**Date picker, e.g. 'Shipping date'**

```javascript title="Core Script"
checkoutCustomElements: [
  {
    name: "shipping-date",
    translations: {
      en: {
        title: "Shipping Date",
        detail:  "Please select your preferred shipping date"
      }
    },
    attributes: {
      required: true,
      type: "date"
    }
  },
],
```

**Custom text, e.g. 'Tax ID Reference'**

```javascript title="Core Script"
checkoutCustomElements: [
  {
      translations: {
          en: {
              title: "Tax ID Reference",
              detail: "Please enter your Tax ID reference"
          }
      },
      name: "tax-id",
      attributes: {
          required: false,
          type: "text",
          placeholder: "Enter Tax ID reference",
          minlength: 4,
          maxlength: 600
      }
  },
],
```

**Drop-down menu ("select" menu), e.g. 'Seasonal information'**

Options can be grouped under headings (`groupName`), as in this example with "Group A" and "Group B".

```javascript title="Core Script"
checkoutCustomElements: [
 {
    translations: {
      en: {
        title: "Option Title",
        detail: "Select Option Detail"
      }
    },
    name: "select-option-test",
    attributes: {
      required: true,
      type: "select",
    },
    options: [
      {
        translations: {
          en: {groupName: "Group A"},
        },
        items: [
          {value: "Option 1", 
            translations: {
              en: {
                label: "Option 1"
              }
          }
          },
          {value: "Option 2", 
            translations: {
              en: { label: "Option 2" }
            }
          }
        ],
      },
      {
          translations: {
          en: { groupName: "Group B" }
        },
        items: [
          {value: "Option 3", 
            translations: {
              en: { label: "Option 3" }
            }
          },
          {value: "Option 4", 
            translations: {
              en: { label: "Option 4" }
            }
          }
        ],
      }
    ]
  }
],
```

**Custom text, e.g. 'Shipping instructions'**

```javascript title="Core Script"
checkoutCustomElements: [
  {
      translations: {
          en: {
              title: "Shipping instructions field",
              detail: "Please confirm any shipping instructions for us"
          }
      },
      name: "shipping-instructions",
      attributes: {
          required: true,
          type: "text",
          placeholder: "Shipping instructions field",
          minlength: 4,
          maxlength: 600
      }
  },
],
```

**Number, e.g. 'Contact phone number'**

```javascript title="Core Script"
checkoutCustomElements: [
  {
      translations: {
          en: {
              title: "Contact phone number",
              detail:  "Please supply a phone number to allow us to contact you"
          }
      },
      name: "number-field",
      attributes: {
          type: "number",
          min: 10,
          max: 25,
      }
  },
],
```

**File attachments (e.g. Purchase Order file upload)**

File uploads are also added as a custom checkout field. See [Let customers upload files at checkout](#file-upload-file-attachments).

**Date picker that requires date at least 1 day in future**

```javascript title="Core Script"
checkoutCustomElements: [
  {
    name: "delivery-date",
    translations: {
      en: {
        title: "Delivery Date",
        detail:  "Delivery date must be at least one day in future."
      }
    },
    attributes: {
      required: true,
      type: "date",
      min: ((d) => { 
        d.setDate(d.getDate() + 1); 
        return d.toISOString().slice(0,10); 
      })(new Date())
    }
  },
],
```

**Date picker that restricts by weekends and specific dates**

This uses `onChange` to block past dates (and today after 12:00 UK time), weekends and the listed UK bank holidays, with a different message for each. Update the bank holiday list for the current year.

```javascript title="Core Script"
checkoutCustomElements: [
  {
  translations: {
    en: {
      title: "Delivery Date",
      detail: "Delivery unavailable on weekends.",
      'select-mon-fri': "Date must be Monday-Friday",
      'select-date-in-future': "Select a date in the future",
      'select-non-bank-holiday': "Select another date which is not a UK bank holiday",
    },
  },
  name: "delivery-date-requested",
  attributes: {
    required: true,
    type: "date"
  },
  onChange(val, el) {
    const [year, month, date] = val.split('-');
    const selectedDate = new Date(
      Number(year),
      Number(month)-1,
      Number(date), 
      0,
      0,
      0,
      0
    );
    const now = new Date()
    const ukTime = now.toLocaleString(
      'en-GB',
      {
        hour: '2-digit',
        hour12: false,
        timeZone: 'Europe/London'
      }
    );

    const earliestDeliveryDate = new Date(
      now.getFullYear(),
      now.getMonth(),
      now.getDate() + (Number(ukTime) >= 12 ? 1 : 0)
    )

    const ukBankHolidays = [
      '07/04/2023',
      '10/04/2023',
      '01/05/2023',
      '08/05/2023',
      '29/05/2023',
      '28/08/2023',
      '25/12/2023',
      '26/12/2023',
    ];

    const selectedDateStr = new Intl.DateTimeFormat('en-GB', { dateStyle: 'short' })
      .format(selectedDate);

    let messageTranslationKey
    switch (true) {
      // Date is in the past
      case selectedDate < earliestDeliveryDate:
        messageTranslationKey = 'select-date-in-future'
        break;
      // Day is weekend
      case [0, 6].includes(selectedDate.getDay()):
        messageTranslationKey = 'select-mon-fri'
        break;
      // Is bank holiday
      case ukBankHolidays.includes(selectedDateStr):
        messageTranslationKey = 'select-non-bank-holiday'
        break;
    }

    return {
      valid: messageTranslationKey === undefined,
      messageTranslationKey
    }
  }
}
],
```

**Checkbox to require customer confirmation**

```javascript title="Core Script"
checkoutCustomElements: [
  {
    translations: {
      en: {
        title: "I agree to the terms and conditions",
        detail: "Please confirm you've read and agree to the terms and conditions",
      },
    },
    name: "confirmation",
    attributes: {
      required: true,
      type: "checkbox"
    },
  },
],
```

## Reference

### Custom field settings

Settings for fields added in the Core Script, for your developer:

| Key | What it does |
| --- | --- |
| `name` | The name of the field. It's shown in your eCommerce platform but not to customers. **Required** (standard fields use `id` instead). |
| `translations` | An object of customer-facing text, keyed by two-letter language code ([ISO 639-1](https://www.wikiwand.com/en/ISO_639-1)). **Required.** |
| `title` | Inside `translations`: the text shown in bold above the field. **Required.** |
| `detail` | Inside `translations`: small helper text shown under the field, for example to explain what to enter. |
| `attributes` | HTML attributes for the field, which set its type and validation: `max`, `maxlength`, `min`, `minlength`, `name`, `pattern`, `placeholder`, `required` (default `false`), `disabled` (default `false`), `step` and `type` (default `text`). Some attributes only apply to certain types; see the [MDN input attributes reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes). |
| `options` | For `select` fields: the drop-down options, optionally in named groups. |
| `onChange` | A function that validates the value and returns a message key from `translations` if it's invalid. |

To change the default look of the fields, see [Frontend integration](https://docs.sparklayer.io/developers/frontend.md).

### Supported field types

| Field type | What the customer enters |
| --- | --- |
| `text` | Free text |
| `select` | A choice from a drop-down menu |
| `number` | A number |
| `date` | A date, DD/MM/YYYY |
| `time` | A time, 00:00 |
| `week` | A week (for example, week 4) |
| `month` | A month of the year (for example, 12) |
| `datetime-local` | A date and time, DD/MM/YYYY 00:00 |
| `checkbox` | A tick box (allows multiple selections) |
| `tel` | A phone number |
| `email` | An email address |
| `url` | A website URL |
| `file` | A file attachment (Growth, Pro and Enterprise plans) |

## FAQs

**Do I need a developer to add checkout fields?**

Not for standard or custom fields: add them at **Storefront > Options > Checkout** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Checkout** in the Shopify app. File uploads and validation rules need a developer. See [What you can do without code](#what-you-can-do-without-code).

**Can I use custom checkout fields on Wix?**

**Wix only:**

Yes, with a developer. They add the fields in code, with `checkoutCustomElements` in the `window.sparkWixOptions` script. See [JavaScript options](https://docs.sparklayer.io/help/platforms/wix/install.md#javascript-options) and [Wix limitations](https://docs.sparklayer.io/help/platforms/wix/limitations.md).

**What's the difference between checkout fields and the Additional Information field?**

**Additional Information** is one free-text box (up to 512 characters), saved to the order notes. You can add as many checkout fields as you need, each with its own type and validation. See [Cart and checkout](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md#set-up-the-additional-information-field-po-number).

**Can I raise the 20MB file size limit?**

No. 20MB is the maximum. You can set a lower limit with `maxsize`.

**Why can't I open an uploaded file from the Shopify order?**

**Shopify only:**

Shopify stores only a reference to the file. Download it from the customer's account (as the customer or a sales agent) or through the Files API. See [Download uploaded files](#download-uploaded-files).


---

# Payment methods

URL: https://docs.sparklayer.io/help/ordering/payment-methods

Choose how each B2B customer group can pay (on account, by invoice or by card), see how each method affects the order, and rename or reorder them at checkout.

> **Quick summary**
>
> - SparkLayer has 3 B2B payment methods. With **Pay on Account** and **Pay by Invoice**, the customer orders now and pays you later. With **Pay Online by Card**, they pay in your store's checkout straight away.
> - Choose the methods for each customer group in its **Payment methods** rule at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app, where they have different names: see [Payment method names](#names). On Shopify, you can also give a method a discount or surcharge, or hide it, when an order meets your conditions: see [Payment method rules](https://docs.sparklayer.io/help/ordering/payment-method-rules.md).
> - On Shopify, on-account and invoice orders arrive as draft orders unless you turn on **Auto-complete draft orders**. Card orders arrive paid.
> - To let customers ask for a quote instead of paying, turn on the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md). Quotes aren't a payment method.

## How it works

On the **Review & Pay** step of the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md), customers pick from the payment methods their customer group allows. Their choice decides whether they pay now, and how the order arrives in your store.

| Payment method | For the customer | For you and the order |
| --- | --- | --- |
| **Pay on Account** | Checks out without payment details. The order is charged to their account, for example on Net 30 terms. | An offline method. You can set a [credit limit and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) for each customer and collect payment later. |
| **Pay by Invoice** | Checks out without payment details, and pays later, for example on Net 30 terms. | An offline method. You take payment outside the store, for example by bank transfer, often against an [invoice](https://docs.sparklayer.io/help/ordering/invoices.md). You can set [net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md), but there's no credit limit. |
| **Pay Online by Card** | Pays straight away in your store's standard checkout, by card or any other method your store offers. Sometimes called pro forma payment. | The order arrives paid (completed), with nothing to collect. |

### Which method to offer

| If you want customers to... | Offer |
| --- | --- |
| Pay before you ship, for example new customers | **Pay Online by Card** |
| Order within a credit limit and pay on terms such as Net 30 or Net 60 | **Pay on Account**, with [credit limits and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) |
| Order now and pay later against an invoice, for example by bank transfer, with or without net terms but no credit limit | **Pay by Invoice** |
| Agree a price with your team before ordering | The [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md) |
| Encourage a method with a discount, cover card fees with a surcharge, or offer a method only for some orders | [Payment method rules](https://docs.sparklayer.io/help/ordering/payment-method-rules.md), on Shopify |

A group can have several methods, for example card and on account for long-standing customers, and card only for new ones.

**Shopify only:**

To follow each method from checkout to payment, step by step, try the interactive guide [How payments work](https://docs.sparklayer.io/help/guides/how-payments-work.md).

### Which payment methods work with the SparkLayer checkout?

**Shopify only:**

| Payment method | Works? | How |
| --- | --- | --- |
| **Card gateways**, such as Shopify Payments or PayPal | Yes | Through **Pay Online by Card**, which takes the customer to Shopify's checkout. |
| **Manual (custom) methods**, such as Zelle or bank transfer | Yes | Zelle isn't a Shopify automated gateway. Add it as a manual payment method in **Settings > Payments** ([open in the Shopify admin](https://admin.shopify.com/settings/payments)), and it shows in Shopify's checkout with **Pay Online by Card**. Or offer **Pay by Invoice** and explain how to pay in a [payment method message](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md#add-a-message-for-each-payment-method). |
| **ACH bank transfer** | Partly | It shows at Shopify's own payment step, the last step of the checkout, with **Pay Online by Card**. Full ACH support in the SparkLayer checkout is in development, with no date yet. |
| **Pay on Account** and **Pay by Invoice** | Yes | SparkLayer's own methods. The customer checks out without payment details and you collect payment later. |
| **Quotes** | Yes | Not a payment method: the customer chooses how to pay when they complete the quote. See [Set up quotes](https://docs.sparklayer.io/help/ordering/quoting.md). |
| **Shopify gift cards** | With card checkout only | Only in Shopify's checkout, with **Pay Online by Card**. Not with **Pay on Account** or **Pay by Invoice**. |

Each order has one payment method, so a customer can't split an order between methods, such as part on account and part by card.

### How orders arrive in your store

Which payment method the customer chooses decides how the order arrives in your platform: paid and ready to fulfil, or waiting for you to collect payment.

**Shopify:**

How B2B payment methods work with SparkLayer and Shopify, starting from the B2B checkout (SparkLayer):

- **Pay online by card (upfront):**
  - If it's a **sales agent order**, or a **company user order**, an email is sent to the customer to complete payment. The customer clicks the link, pays in the **Shopify checkout** and the order is completed in Shopify.
  - Otherwise the customer pays in the **Shopify checkout** and the order is completed in Shopify.
- **Payment on account or by invoice:** the order is completed in SparkLayer ("Order completed (SparkLayer)").
  - If **auto-complete draft orders** is on, a completed order is created in Shopify.
  - If it's off, a draft order is created in Shopify, which becomes a completed order once it's manually marked as complete.

| Payment method | How the order arrives |
| --- | --- |
| **Pay on Account** and **Pay by Invoice** | A [draft order](https://help.shopify.com/en/manual/orders/create-orders) by default, so you can make changes before you take payment and fulfil. To create completed orders instead, turn on **Auto-complete draft orders**. |
| **Pay Online by Card** | The customer pays in the Shopify checkout and the order arrives completed. If they don't finish paying, the order still shows in your Shopify draft orders. |
| **Pay Online by Card**, chosen by a **sales agent** or **company user** | The customer is emailed to complete payment, then the order continues as normal. |

**Auto-complete draft orders** is at **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app. See [Complete draft orders automatically](https://docs.sparklayer.io/help/ordering/automation-and-workflows.md) and [Shopify payment methods](https://docs.sparklayer.io/help/platforms/shopify/customisations/payment-methods.md).

**Wix:**

Orders are created in your Wix admin under **Sales > Orders**. Every method except **Pay Online by Card** creates an unpaid order.

| Payment method | How the order arrives |
| --- | --- |
| **Pay on Account** | Payment status "UNPAID". Mark it as paid once you've received payment, for example offline. |
| **Pay by Invoice** | Payment status "UNPAID". Mark it as paid once you've received payment. |
| **Pay Online by Card** (**Card at checkout** in the customer group) | Payment status "PAID". You can fulfil it straight away. |

Pay Online by Card takes customers to the Wix checkout, with all the Wix payment methods you've set up, such as card or PayPal.

**Other platforms:**

| Payment method | What happens |
| --- | --- |
| **Pay on Account** and **Pay by Invoice** | The customer places the order without entering payment details. |
| **Pay Online by Card** | The customer goes to your store's checkout, enters their card details and sees the payment methods you've set up there. |

For how orders are created on your platform, see the [developer docs](https://docs.sparklayer.io/developers.md).

## Choose which payment methods a customer group can use

1. 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 click the group's name. To change every group, click **Edit** on the base customer group.
2. Under **Inherited rules**, click **+ Override** next to **Payment methods** (on the base group, **+ Customize**). The rule moves up to **Customized rules**.
3. Tick the methods the group can use: **Pay by invoice** ("Place an order and be invoiced later"), **Payment on account** ("Order on account, e.g. net terms and credit") and **Card at checkout** ("Pay online by card").
4. Click **Save**.

Groups inherit the base customer group's methods until you override them. Click **Reset** on the rule to hand it back. See [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md#choose-payment-methods).

## Add a discount or surcharge, or hide a method

**Shopify only:**

Under each method you tick, click **Add rule** to change the method for orders that meet your conditions:

- **Apply a discount**, such as 2% off for paying by invoice.
- **Apply a surcharge**, such as a 1.5% fee on card payments.
- **Hide this payment method**, such as **Pay on Account** on orders over £5,000.

Customers see each method's discount or surcharge next to it on **Review & Pay**. Laws on surcharges vary by country, so check them where you sell before you add one. Rules need the Growth plan or above and Core Script 4.13.0 or later. See [Payment method rules](https://docs.sparklayer.io/help/ordering/payment-method-rules.md).

**More detail**

**Shopify only:**

On Shopify, you can also let a [company](https://docs.sparklayer.io/help/customers/companies.md) pay later, or stop it, whatever its group says. Open the company at **Companies** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/companies)), or **SparkLayer Wholesale > Companies** in the Shopify app and use **Let them pay later** ("They order now and pay by invoice, up to their credit limit."). Each location has its own **Pay later** setting.

## Set up net terms and credit limits

[Net terms](https://docs.sparklayer.io/help/glossary.md#net-terms) (such as Net 30) are how many days a customer has to pay an order they didn't pay for at checkout, so they apply to both **Pay on Account** and **Pay by Invoice**. A credit limit applies to **Pay on Account** only. Both are on every plan. You set them on each customer in a [metafield](https://docs.sparklayer.io/help/glossary.md#metafields) (an extra field on the customer record in your store admin). Customers see them in the **Financials** section of [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md). See [Credit limits and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md).

## Rename payment methods

Change the names customers see at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app, without code: add an override for the key and enter the new name. See [Change checkout text](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md#change-checkout-text).

| Default name | Translation key |
| --- | --- |
| **Pay by Invoice** | `cart.checkout.payment-method.full.paymentByInvoice` |
| **Pay on Account** | `cart.checkout.payment-method.full.paymentOnAccount` |
| **Pay Online by Card** | `cart.checkout.payment-method.full.upfrontPayment` |

**Core Script code for your developer**

A developer can set the same names in your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting):

```javascript title="Core Script"
translations: {
  en: {
    "cart.checkout.payment-method.full.paymentByInvoice": "Pay by Invoice",
    "cart.checkout.payment-method.full.paymentOnAccount": "Pay on Account",
    "cart.checkout.payment-method.full.upfrontPayment": "Pay Online by Card",
  }
},
```

To explain a method, such as how Pay by Invoice works, add a message under it. See [Add a message for each payment method](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md#add-a-message-for-each-payment-method).

## Change the order and default payment method

Customers see payment methods in a set order, and the first is selected by default. To change the order without code:

1. Go to **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app and open **Checkout**.
2. Under **Payment methods, in order**, drag the methods into the order you want.
3. Click **Save and publish**.

The order only affects methods the customer's group can use.

**Core Script code for your developer**

A developer can set `paymentMethodsOrder` in your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting) instead, using the Core Script names in [Payment method names](#names). Here, Payment on account is first, so it's the default:

```javascript title="Core Script"
paymentMethodsOrder: [
  "paymentOnAccount",
  "paymentByInvoice",
  "upfrontPayment",
],
```

To make card payment (`upfrontPayment`) the default, move it to the top:

```javascript title="Core Script"
paymentMethodsOrder: [
  "upfrontPayment",
  "paymentOnAccount",
  "paymentByInvoice",
],
```

## Choose which card payment options customers see (Shopify)

**Shopify only:**

**Pay Online by Card** takes customers to the Shopify checkout, with every [Shopify payment method](https://help.shopify.com/en/manual/payments/additional-payment-methods) you've set up, such as credit card, PayPal or cash on delivery.

To hide some of them from B2B customers on Shopify:

1. Install a Shopify app that hides payment methods, such as [ETP Hide and Sort Payment Methods](https://apps.shopify.com/etp-hide-sort-payments?) or [Payfy Conditional Payments](https://apps.shopify.com/payfy-conditional-payments).
2. In the app, add a rule for customers with the `b2b` tag, and choose the methods to hide, such as PayPal and Cash on Delivery.

Only Shopify Plus stores can hide the **Credit card** method. This is a limit of Shopify's Payment Customization API.

On other platforms, **Pay Online by Card** shows your standard checkout's payment methods.

## Show payment status to customers

**Shopify only:**

Payments visibility lets customers see whether each order is paid, their payment history and what they owe, in [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md). It's for Shopify only.

1. Go to **Settings > Configurations > Ordering** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Ordering** in the Shopify app.
2. Turn on **Payments visibility** ("Show the payment status of orders in the My Account area").
3. Click **Save**.

It's the same setting as **Show payment status** at **Storefront > Options > My Account** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > My Account** in the Shopify app: turning on either turns on both. Once it's on:

- The My Account order list has a **Payment** column, showing **Paid** or **Unpaid**. It updates when you change the payment status in Shopify.
- The order's [timeline](https://docs.sparklayer.io/help/customers/timeline.md) logs each payment, with the amount and date, such as "US$666.90 paid against order".
- With [Xero](https://docs.sparklayer.io/help/integrations/accountancy/xero.md), payments against Xero invoices appear as transactions on the order.

## Show a real-time account balance

**Shopify only:**

With Payments visibility on, SparkLayer keeps a real-time account balance for each customer. The **Financials** section of My Account shows their **Payment terms**, **Unpaid Balance** and **Credit Limit**.

SparkLayer starts from an **opening balance** (what the customer owed on a given date), then tracks every new order and payment. This works with Shopify, Xero and QuickBooks Online, so customers can see which orders are paid or outstanding, and your team gets fewer balance queries.

### Set an opening balance

**Shopify only:**

The opening balance goes in the same customer metafield as the credit limit: **Credit Limit and Account Balance** (namespace `sparklayer`, key `payment_on_account`). To set up the metafield, see [Credit limits and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md).

1. In the form below, enter the **Balance** the customer owes and the **Balance date** it applies from, plus their **Credit limit** and **Net terms** if they have them: the value replaces everything in the field. It writes the date in the format SparkLayer needs.
2. In the Shopify admin, go to **Customers** ([open in the Shopify admin](https://admin.shopify.com/customers)) and open the customer.
3. Paste the value into the **Credit Limit and Account Balance** metafield, replacing what's there, and save the customer.

| Property | What it is | Example |
| --- | --- | --- |
| `balance` | The amount owed on a specific date. | `150.00` |
| `balance_date` | The date and time of the balance, in RFC 3339 format. | `2025-01-01T18:00:00+08:00` |

Whenever you update the metafield, SparkLayer recalculates the balance from the new values.

## Payment method names

Each method has a different label in each part of SparkLayer: the checkout, a customer group's **Payment methods** rule at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app, and **Payment methods, in order** at **Storefront > Options > Checkout** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Checkout** in the Shopify app.

| Buyers see at checkout | Customer group rule | Storefront options | Core Script name |
| --- | --- | --- | --- |
| **Pay on Account** | **Payment on account** | **Payment on account** | `paymentOnAccount` |
| **Pay by Invoice** | **Pay by invoice** | **Payment by invoice** | `paymentByInvoice` |
| **Pay Online by Card** | **Card at checkout** | **Upfront payment** | `upfrontPayment` |
| **Request for Quote** (retired) | – | **Quote** | `quote` |

## FAQs

**Why do customers only see card payment, with Pay by Invoice not showing?**

Their customer group only allows **Card at checkout**. Customers see the payment methods their group allows, so a card-only group shows credit card (upfront) payment and nothing else. Tick **Pay by invoice** or **Payment on account** on the group: see [Choose which payment methods a customer group can use](#choose-which-payment-methods-a-customer-group-can-use).

**Shopify only:**

On Shopify, also check the customer's company has **Let them pay later** on. A company or location with pay later off can only pay by card. See [Customers only see card payment](https://docs.sparklayer.io/help/troubleshooting.md#customers-only-see-card-payment).

**How do I turn off card payment and offer pay by invoice only?**

On the customer group, untick **Card at checkout** and tick **Pay by invoice**, then click **Save**. Customers in the group then check out without paying upfront, and on Shopify the order arrives as a draft order by default, for you to invoice. See [Choose which payment methods a customer group can use](#choose-which-payment-methods-a-customer-group-can-use).

**How often does the customer's balance update?**

Whenever a new order is placed, or a payment syncs from your store or accounting tool (Xero or QuickBooks Online).

**Can I update balances in bulk?**

Yes. Update the **Credit Limit and Account Balance** metafield for several customers with Shopify's bulk editor or a CSV import tool.

**Why is the "Payment on Account" metafield not updating?**

The metafield keeps the values you set. The real-time balance is calculated and held in SparkLayer, not written back to the metafield.

**Can I still use Request for Quote?**

No. Quotes use the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md), and Request for Quote can't be selected in a customer group.

**Can I add a message to explain a payment method?**

Yes. A message can show under each payment method on **Review & Pay**, the same for every customer. See [Add a message for each payment method](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md#add-a-message-for-each-payment-method).

**Can I preselect a different payment method for each customer group?**

No. The first method in **Payment methods, in order** is selected by default, and the order is the same for every customer group. See [Change the order and default payment method](#change-the-order-and-default-payment-method). If a [payment method rule](https://docs.sparklayer.io/help/ordering/payment-method-rules.md) hides the first method, the next one shown is selected.

**Can I charge a fee for card payments?**

Yes, on Shopify. Add a [payment method rule](https://docs.sparklayer.io/help/ordering/payment-method-rules.md) to **Card at checkout** that applies a surcharge, as a percentage or a fixed amount. Laws on surcharges vary by country, so check them where you sell first.

**Can customers pay with Zelle or ACH?**

Zelle works as a Shopify manual payment method. ACH bank transfer shows at Shopify's own payment step, and full ACH support is in development. See [Which payment methods work with the SparkLayer checkout?](#which-payment-methods-work-with-the-sparklayer-checkout)


---

# Payment method rules

URL: https://docs.sparklayer.io/help/ordering/payment-method-rules
Applies to: Shopify

Add a discount or surcharge to a payment method, or hide it, when an order meets your conditions, such as its sub-total, items, credit or shipping destination.

> **Quick summary**
>
> - A payment method rule gives a payment method a discount or a surcharge, or hides it, when an order meets your conditions, for example a 2% surcharge on card payments under £500.
> - Add rules to each payment method in a customer group's **Payment methods** rule, at **Customers > Groups > Payment methods** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups > Payment methods** in the Shopify app.
> - Needs the Growth plan or above and Core Script 4.13.0 or later. For Shopify stores.
> - Rules don't apply to quotes.

## How it works

A rule belongs to one payment method in one customer group. It has 2 parts:

- **When:** the conditions the order must meet, such as an order sub-total of at least £500. A rule with no conditions applies to every order.
- **Then:** the outcome. **Apply a discount**, **Apply a surcharge** or **Hide this payment method**.

An order must meet every condition on a rule for it to apply. Every rule that applies is used, so a method can have a discount and a surcharge at the same time. There's no priority to set: SparkLayer always works them out in the same order.

How payment method rules are applied to an order:

1. **Hide rules**: A method with a matching hide rule isn't shown, and its other rules don't apply
2. **Discounts**: Your normal discounts, then payment rule discounts, off the net sub-total
3. **Surcharges**: Added to the net sub-total after every discount
4. **Shipping and tax**: Worked out with the surcharge included

> **Check surcharge laws where you sell**
>
> Laws on surcharges, and on charging different amounts for different payment methods, vary by country and region. Some places limit or ban surcharges on certain payment methods. Check the rules in every country you sell to before you add a surcharge. You're responsible for making sure your rules comply: SparkLayer doesn't check them against any law.

### A worked example

A customer pays by card for £1,000 (net) of products, with a 10% off coupon. **Card at checkout** has 2 rules:

- **Rule 1:** a 5% discount, with no conditions.
- **Rule 2:** a 2% surcharge, when the order sub-total is at least £500.

| Step | Amount | Order sub-total |
| --- | --- | --- |
| Products | £1,000.00 | £1,000.00 |
| 10% off coupon | -£100.00 | £900.00 |
| Rule 1: 5% of £900.00 | -£45.00 | £855.00 |
| Rule 2: 2% of £855.00 | +£17.10 | £872.10 |
| Shipping and tax | Worked out on £872.10 | |

Rule 2's minimum is checked against £900.00: the sub-total after the coupon, before the payment rule discount. See [Which sub-total conditions use](#which-sub-total-conditions-use).

## Add a rule

1. 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 click the group's name. To add rules for every group, click **Edit** on the base customer group.
2. If **Payment methods** is under **Inherited rules**, click **+ Override** next to it (on the base group, **+ Customize**).
3. Under a ticked payment method, click **Add rule**.
4. Under **When**, tick the conditions the order must meet and fill them in. To apply the rule to every order, leave them all unticked.
5. Under **Then**, choose **Apply a discount**, **Apply a surcharge** or **Hide this payment method**.
6. For a discount or surcharge, choose **Percentage** or **Fixed amount**, and enter the amount.
7. Click **Update customer group**.

**More detail**

- Groups that inherit the **Payment methods** rule inherit its payment method rules too.
- Unticking a payment method deletes its rules when you save.
- **Reset** on the **Payment methods** rule deletes the group's rules, and the group goes back to the inherited methods and rules.

## Conditions

| Condition | The rule applies when | Notes |
| --- | --- | --- |
| **Order sub-total** | The order's net sub-total is between the **Minimum** and **Maximum** | Excludes shipping and tax. See [Which sub-total conditions use](#which-sub-total-conditions-use) |
| **Order items** | The number of items is between the **Minimum** and **Maximum** | Count the **Quantity across all line items** or the **Number of line items**. Free products from discounts and custom line items count |
| **Available credit** | The customer's remaining credit is between the **Minimum** and **Maximum** | How much [credit](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) they have left on their account when they reach checkout. A customer with no credit limit meets any minimum and never meets a maximum |
| **Products** | The order contains a product that matches any of your filters | Filter on **SKU**, **Shopify Vendor** or **Shopify Tags**. Values must be spelled as in your store, but capitals don't matter |
| **Pre-order items** | The cart contains a pre-order item, or contains none | A pre-order item is one the customer can order without stock. This doesn't check that the other items are in stock |
| **Shipping destination** | The shipping address is in one of the **Countries** you choose | Narrow a country to some regions, or leave its regions empty for the whole country. The billing address isn't checked |

The minimum is included and the maximum isn't: with a **Maximum** of £100, the rule applies to orders up to £99.99. Amounts exclude tax.

### Which sub-total conditions use

**Order sub-total** is checked against the net sub-total after your normal [discounts](https://docs.sparklayer.io/help/pricing/discounts.md) and before any payment rule discount. This is the same for every rule, whatever its outcome.

For example, a group has a 10% payment rule discount and a surcharge for orders of at least £950. On a £1,000 order, the surcharge still applies, because £1,000 meets the minimum. It's then worked out on £900, the sub-total after the discount.

## Outcomes

| Outcome | What happens |
| --- | --- |
| **Apply a discount** | Taken off the net sub-total, after all your other discounts. A **Percentage** or a **Fixed amount** |
| **Apply a surcharge** | Added to the net sub-total after every discount, before shipping and tax. A **Percentage** or a **Fixed amount**. It's taxed at your store's default tax rate, so it adds to the order's tax as well as its total |
| **Hide this payment method** | The method isn't shown while the conditions match. Keep at least one method that no hide rule matches. To hide a method from every order, untick it instead |

Fixed amounts and money conditions are in the group's currency, and aren't converted: 5 means £5 in a GBP cart and €5 in a EUR cart.

### When several rules apply

- **Hide wins.** If a hide rule matches, the method is hidden and its discount and surcharge rules don't apply.
- **Discounts all come off the same amount.** A 10% and a 20% payment rule discount on a £900 sub-total take £90 and £180 off, £270 in all, in any order.
- **Surcharges add up**, and each percentage is worked out on the same amount. A 2% and a 3% surcharge on £855 add £42.75. A fixed surcharge is added as it is.
- **Surcharges count towards shipping.** Shipping is worked out after the surcharge, so a surcharge can move an order into a different shipping rate based on order total, such as free shipping over £1,000.
- **Payment rule discounts aren't limited by compatibility.** They apply alongside any other discount, whatever its **Can be used with** setting.

## What customers see at checkout

On **Review & Pay** in [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md):

- Each payment method shows its discounts and surcharges, such as `-5%` or `+£5.00`, so customers can compare before they choose.
- The totals list each payment rule discount, such as "Card payment discount (5%)", and a **Surcharge** line, excluding tax.
- A hidden method isn't shown. If it was selected, the first method still shown in **Payment methods, in order** is selected instead.

Rules apply from **Review & Pay**, not earlier in the cart. To explain a surcharge or discount to your customers, add a [message for the payment method](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md#add-a-message-for-each-payment-method).

## What the order looks like in Shopify

In Shopify, the order shows:

- **A surcharge** as a line item named **Surcharge**, with a quantity of 1. Its tax is in the order's tax, as at checkout.
- **A payment rule discount** as lower line item prices, the same as other SparkLayer discounts. It's listed in the order's **B2B Discount Data** with its other discounts. See [See discount details on an order](https://docs.sparklayer.io/help/pricing/discounts.md#see-discount-details-on-an-order).

## Change the text customers see

Change these in **Translation overrides**: see [Change checkout text](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md#change-checkout-text). `{amount}` is the rule's amount, such as `5%` or `£10.00`.

| Default text | Key |
| --- | --- |
| Card payment discount (\{amount}) | `cart.checkout.discount.payment-rule.upfrontPayment` |
| Pay on account discount (\{amount}) | `cart.checkout.discount.payment-rule.paymentOnAccount` |
| Invoice payment discount (\{amount}) | `cart.checkout.discount.payment-rule.paymentByInvoice` |
| Surcharge | `global.totals.surcharge` |
| View discounts | `cart.checkout.discount.cta-view-only` |
| Sorry, your order wasn't placed as your total changed. Please check it and try again. | `cart.validation-messages.payment-method-not-calculated` |

**View discounts** opens the list of discounts when a payment rule discount applies and your store has no coupon codes. The amounts shown next to each payment method, and the **Surcharge** line item name in Shopify, can't be changed.

**Core Script code for your developer**

```javascript title="Core Script"
translations: {
  en: {
    "cart.checkout.discount.payment-rule.upfrontPayment": "Card payment discount ({amount})",
    "global.totals.surcharge": "Card fee",
  }
},
```

## Limits

| Limit | Value |
| --- | --- |
| Rules per payment method | 5 |
| Filters in a **Products** condition | 25 |
| Payment methods | **Pay by invoice**, **Payment on account** and **Card at checkout** |
| Plan | Growth or above |
| Core Script | 4.13.0 or later. Check **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 |
| Price list | The customer group, or a group it inherits from, needs a price list, which sets the currency of its rules |
| Quotes | Rules don't apply to quotes, from the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md) or the retired Request for Quote |

## FAQs

**Can I charge a fee for card payments?**

Yes. Add a rule to **Card at checkout** with **Apply a surcharge**, as a percentage or a fixed amount. Leave the conditions empty to charge it on every card order. Check the surcharge laws in each country you sell to first: see [How it works](#how-it-works).

**Can I give a discount for paying by card?**

Yes. Add a rule to **Card at checkout** with **Apply a discount**. It comes off after your other discounts, and customers see it next to the method at checkout.

**Why didn't my rule apply?**

Check that the order meets every condition on the rule, and that:

- The maximum isn't included: a **Maximum** of £100 doesn't match a £100 order.
- **Order sub-total** is checked after your normal discounts, and excludes shipping and tax.
- The customer is in the group you added the rule to, or one that inherits its **Payment methods** rule.
- A hide rule on the same method doesn't match, as it stops the method's other rules.
- Your Core Script is 4.13.0 or later.

**Is the surcharge taxed?**

Yes, at your store's default tax rate. Its tax is added to the order's tax at checkout, and the order total includes it.

**Can a surcharge give an order free shipping?**

Yes. Shipping is worked out after the surcharge, so it counts towards shipping rates based on order total. A surcharge can move an order over a free shipping threshold.

**Does a surcharge count towards a customer's credit limit?**

Yes. **Pay on Account** checks the order's total with tax, including its payment rule discounts and surcharges. If that's more than the customer's available credit, they can't use it for the order. See [Credit limits and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md).

**What happens to the Available credit condition when a customer has no credit limit?**

A customer with no credit limit meets any **Minimum** and never meets a **Maximum**. For example, a rule that hides **Pay on Account** when available credit is under £500 never hides it from them.

**Can I set different amounts for each currency?**

No. Amounts are in the group's currency and aren't converted, so a fixed surcharge of 5 is £5 in a GBP cart and €5 in a EUR cart. A percentage works the same way in every currency.

**Do payment method rules apply to quotes?**

No. Rules don't apply to quotes from the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md), and you can't add them to the retired Request for Quote method.


---

# Credit limits and net terms

URL: https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing

Give B2B customers credit limits, account balances and net terms such as Net 30 using SparkLayer metafields, and choose how to send or attach their invoices.

> **Quick summary**
>
> - Give each B2B customer a [credit limit](https://docs.sparklayer.io/help/glossary.md#credit-limit), an account balance and [net terms](https://docs.sparklayer.io/help/glossary.md#net-terms) (7 to 90 days). Enter them on the customer's record in your store admin, in the [metafield](https://docs.sparklayer.io/help/glossary.md#metafields) **Credit Limit and Account Balance** (`sparklayer.payment_on_account`).
> - Customers see them in the **Financials** section of [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md). By default, **Pay on Account** is turned off for an order over the credit limit.
> - Net terms are how many days a customer has to pay an order they didn't pay for at checkout, with **Pay on Account** or **Pay by Invoice**. Credit limits only apply to **Pay on Account**. On Shopify, Pay on Account orders arrive as draft orders with Shopify's payment terms filled in.
> - Credit limits, balances and net terms are on every plan. Send invoices with [SparkLayer Invoices](https://docs.sparklayer.io/help/ordering/invoices.md) (automatic PDF invoices, payment reminders and your own invoice template, on Growth and above), your store, an attached invoice file, or an app such as Sufio.

## How it works

How credit and net terms work, from setup to payment:

1. **Set terms on the customer**: Credit limit, balance and net terms in the customer metafield
2. **Customer sees them**: In the Financials section of My Account
3. **Customer pays on account**: At checkout, within their credit limit
4. **Order arrives with terms**: On Shopify, a draft order with payment terms and a due date
5. **You invoice and collect**: Through SparkLayer Invoices, your store, your own files or an app

**Shopify only:**

To compare Pay on Account with the other payment methods, step by step, see the interactive guide [How payments work](https://docs.sparklayer.io/help/guides/how-payments-work.md).

Before you start:

- **Pay on Account or Pay by Invoice is turned on** for the customer's group. Credit limits only apply to Pay on Account; net terms apply to both. See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md#choose-which-payment-methods-a-customer-group-can-use). 
- **The payment on account metafield exists** in your store. You set it up once: see [The payment on account metafield](#the-payment-on-account-metafield).

### The payment on account metafield

A metafield is an extra field on a record in your store admin. Credit limits, balances and net terms all live in one customer metafield.

**Shopify only:**

On Shopify, SparkLayer can add it for you: 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 and, in the **Metafields** card, click **Configure** next to **SparkLayer metafields**. See [Shopify metafields and data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md).

For other platforms, see the [developer docs](https://docs.sparklayer.io/developers.md).

**Metafield details, for adding it by hand**

| Item | Value |
| --- | --- |
| **Custom data type** | Customers. On Shopify, see [customer metafields](https://admin.shopify.com/settings/custom_data/customer/metafields). |
| **Metafield type** | `JSON` |
| **Namespace** | `sparklayer` |
| **Key** | `payment_on_account` |
| **Value** | Set on each customer record, for example `{"credit_limit":1000,"balance":250,"net_terms":"30_days"}`. Include only the properties you use. |

The value is a short piece of text in a set format (JSON), with these properties:

| Property | What it does | Example |
| --- | --- | --- |
| `credit_limit` | The most the customer can owe you. | `1000` |
| `balance` | What the customer owes you now. | `250` |
| `currency_code` | The currency to show the limit and balance in, if you sell in more than one. | `usd` |
| `net_terms` | The customer's payment terms. See [supported values](#set-net-payment-terms). | `30_days` |
| `balance_date` | The date of an opening balance, for the real-time account balance. See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md#payments---account-balance). | `2025-01-01T18:00:00+08:00` |

### What to enter

Fill in the form and copy the value it writes. Leave out anything you don't use, and enter amounts without a currency symbol.

Add a **Balance date** only for an [opening balance](https://docs.sparklayer.io/help/ordering/payment-methods.md#set-an-opening-balance) on Shopify: the date the **Balance** was owed from, which SparkLayer tracks new orders and payments from. Pick it in the form and it's written in the format SparkLayer needs: the date, the time and your time zone's offset from UTC, such as `2025-01-01T00:00:00+00:00` for midnight on 1 January 2025 in the UK. A date needs a balance with it.

These are the common values, if you'd rather copy one:

| To give the customer | Enter |
| --- | --- |
| A credit limit of 1,000 | `{"credit_limit":1000}` |
| A credit limit of 1,000 and a balance of 250 | `{"credit_limit":1000,"balance":250}` |
| Net 30 payment terms only | `{"net_terms":"30_days"}` |
| A credit limit, a balance and Net 30 terms | `{"credit_limit":1000,"balance":250,"net_terms":"30_days"}` |
| A credit limit and balance in US dollars, if you sell in several currencies | `{"credit_limit":1000,"currency_code":"usd","balance":250}` |
| A credit limit and an opening balance of 250 owed on 1 January 2025 (UK time), for the real-time account balance on Shopify | `{"credit_limit":1000,"balance":250,"balance_date":"2025-01-01T00:00:00+00:00"}` |

## Set a credit limit and account balance

1. Open the customer's record in your store admin. On Shopify, go to **Customers** ([open in the Shopify admin](https://admin.shopify.com/customers)) and open the customer.
2. In the **Credit Limit and Account Balance** metafield, paste the value from the [form](#what-to-enter), for example `{"credit_limit":1000,"balance":250}`. 
3. If you sell in several currencies (see [Shopify Markets and currencies](https://docs.sparklayer.io/help/platforms/shopify/markets-and-currencies.md)), add the customer's currency, for example `{"credit_limit":1000,"currency_code":"usd","balance":250}`.
4. Save the customer.

**Lots of customers? Fill them in one table (Shopify):** in your Shopify admin, go to **Customers**, tick the customers and click **Edit customers**. Click **Columns**, tick **Credit Limit and Account Balance** under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

The balance updates automatically with each successful order, and you can change it by hand at any time. For a balance that also tracks payments, turn on **Payments visibility**: see [Show a real-time account balance](https://docs.sparklayer.io/help/ordering/payment-methods.md#payments---account-balance).

| Where | What the customer sees |
| --- | --- |
| **My Account** | In **Financials**, for example, "Your account balance is £250.00 with a credit limit of £1,000.00", then "Payments may take some time to be updated. Please contact us to discuss payments or credit." |
| **Checkout** | If the cart would exceed their available credit, "Your order currently exceeds your available credit limit".  By default, **Pay on Account** is turned off and they must choose another method, such as **Pay Online by Card**. |

**Check a customer's credit details in SparkLayer**

Open the customer at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app. Under **Financial details**, **Payment on account** shows their **Balance**, **Credit limit**, **Net terms** and **Currency**. These come from the metafield, so change them on the customer's record in your store admin.

### Worked example

Available credit is the customer's `credit_limit` minus their `balance`. The balance is what they owe you, not what they have left to spend.

| What happens | Metafield value | Available credit |
| --- | --- | --- |
| You give a new customer $250 to spend | `{"credit_limit":250,"balance":0}` | $250.00 |
| They place a $77.80 order with **Pay on Account** | SparkLayer updates the balance to `77.80` | $172.20 |
| They try to pay on account for a $200.00 order | No change | $172.20, so checkout is blocked for **Pay on Account** |

Don't set `balance` to 250 to give them $250 to spend. `{"credit_limit":250,"balance":250}` means they already owe you $250, so they've used all their credit.

Checkout blocks the order, rather than warning the customer, because of the customer group's **Prevent placing an order if exceeding credit limit** setting, shown on the group as **Checkout blocked if limit exceeded**. See [Block orders over the credit limit](https://docs.sparklayer.io/help/customers/customer-groups.md#block-orders-over-the-credit-limit).

### Let customers order over their credit limit

By default, a customer can't pay on account for an order over their credit limit. To allow it, change the customer group's **Credit settings** rule:

1. 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 click the group's name. For every group, click **Edit** on the base customer group.
2. Under **Inherited rules**, click **+ Override** next to **Credit settings** (on the base group, **+ Customize**), then **Configure**.
3. Turn off **Prevent placing an order if exceeding credit limit**, then click **Save**.

Customers can then pay on account over their limit, with a message that the order may be delayed and subject to approval. See [Block orders over the credit limit](https://docs.sparklayer.io/help/customers/customer-groups.md#block-orders-over-the-credit-limit).

There's also a store-wide setting at **Settings > Configurations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations** in the Shopify app that lets customers use Pay on Account when an order takes them over their limit.

### Change the credit messages

Change this text without code at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app (see [Change checkout text](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md#change-checkout-text)). `{balance}`, `{creditLimit}` and `{type}` are replaced with the customer's own values.

| Key | Default text |
| --- | --- |
| `account.main.my-details.payment-on-account.detail` | Your account balance is `{balance}` with a credit limit of `{creditLimit}`. |
| `account.main.my-details.payment-on-account.detail-without-limit` | Your account balance is `{balance}`. |
| `account.main.my-details.payment-on-account.net-terms` | Your payment terms are `{type}`. |
| `account.main.my-details.payment-on-account.sub-text` | Payments may take some time to be updated. Please contact us to discuss payments or credit. |
| `cart.checkout.payment-method.credit-unavailable.title` | Your cart currently exceeds your available credit limit |
| `cart.checkout.payment-method.credit-unavailable.message` | Please choose an alternative payment method to complete your order. If you'd like to discuss your payment terms, please contact us. |
| `cart.checkout.payment-method.credit-limit-hit.title` | Your cart currently exceeds your available credit limit |
| `cart.checkout.payment-method.credit-limit-hit.message` | You can place an order but it may be delayed and subject to approval. If you'd like to discuss your payment terms, please contact us. |

`credit-unavailable` messages show when Pay on Account is turned off for an order over the limit. `credit-limit-hit` messages show when you let customers order over it.

**Core Script code for your developer**

A developer can set the same text in your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting):

```javascript title="Core Script"
translations: {
  en: {
    "account.main.my-details.payment-on-account.detail": "Your account balance is {balance} with a credit limit of {creditLimit}.",
    "account.main.my-details.payment-on-account.detail-without-limit": "Your account balance is {balance}.",
    "account.main.my-details.payment-on-account.net-terms": "Your payment terms are {type}.",
    "account.main.my-details.payment-on-account.sub-text": "Payments may take some time to be updated. Please contact us to discuss payments or credit.",

    "cart.checkout.payment-method.credit-unavailable.title": "Your cart currently exceeds your available credit limit",
    "cart.checkout.payment-method.credit-unavailable.message": "Please choose an alternative payment method to complete your order. If you'd like to discuss your payment terms, please contact us.",
    "cart.checkout.payment-method.credit-limit-hit.title": "Your cart currently exceeds your available credit limit",        
    "cart.checkout.payment-method.credit-limit-hit.message": "You can place an order but it may be delayed and subject to approval. If you'd like to discuss your payment terms, please contact us.",
  }
},
```

## Set net payment terms

Net terms tell the customer how many days they have to pay an order they didn't pay for at checkout, such as Net 30. They show as **Payment terms** (for example, "45 days") in **Financials** in My Account.

1. Open the customer's group at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app and tick **Payment on account** (or **Pay by invoice**) in its **Payment methods** rule. See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md#choose-which-payment-methods-a-customer-group-can-use).
2. On the customer's record, add the terms to the payment on account metafield, for example `{"net_terms":"30_days"}`. Use the [form](#what-to-enter) to combine them with a credit limit: it writes `{"credit_limit":1000,"balance":250,"net_terms":"30_days"}` for you.

The customer uses their terms by choosing **Pay on Account** (or **Pay by Invoice**) at checkout. Supported values:

| Net terms | Value |
| --- | --- |
| 7 days | `7_days` |
| 15 days | `15_days` |
| 30 days | `30_days` |
| 45 days | `45_days` |
| 60 days | `60_days` |
| 90 days | `90_days` |

**Shopify:**

Pay on Account orders arrive in Shopify as **draft orders**. SparkLayer ticks **Payment due later** and fills in **Payment terms** (such as "Within 30 days") and **Issue date**, so Shopify shows the due date, such as "Payment due on 19 June 2023 (Net 30)".

To complete these drafts automatically and collect payment later (for example, through your accounting system), turn on **Auto-complete draft orders** at **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app.

To mark net terms orders as paid automatically, and automate more of the process, use our [ready-made Shopify Flows](https://docs.sparklayer.io/help/platforms/shopify/customisations/flow.md).

**Other platforms:**

For how net terms orders are created on your platform, see the [developer docs](https://docs.sparklayer.io/developers.md).

## Choose how to send invoices

| Method | How it works | Best when |
| --- | --- | --- |
| **SparkLayer Invoices** (Growth and above) | A PDF invoice is created for each order, and customers view and download it from My Account. | Your needs are fairly simple and you don't want another app. See [Invoices](https://docs.sparklayer.io/help/ordering/invoices.md). |
| **Send invoices from your store** | You send invoices from your eCommerce platform's admin. | Your needs are basic, or you're testing a B2B invoicing process. See [Send invoices from your store](#send-invoices-from-your-store). |
| **Attach your own invoice** | A metafield links an invoice file to the order, added by hand or automatically. | Another system, such as your ERP or accounting software, already creates invoice files such as PDFs. See [Attach your own invoice](#attach-your-own-invoice-to-an-order). |
| **Third-party app** | Apps such as Sufio integrate with SparkLayer. | You also invoice retail customers, or want more design control. See [Use a third-party invoicing app](#use-a-third-party-invoicing-app). |

**Shopify only:**

To see how each way of invoicing works with **Auto-complete draft orders**, and with Xero or QuickBooks Online, try the interactive guide [How payments work](https://docs.sparklayer.io/help/guides/how-payments-work.md).

### Send invoices from your store

**Shopify:**

Orders with an offline [payment method](https://docs.sparklayer.io/help/ordering/payment-methods.md), such as Pay by Invoice, can arrive in Shopify as draft orders. Shopify's **Send invoice** emails the customer a message and a link to the Shopify checkout.

1. In the Shopify admin, open the draft order.
2. Send the invoice. The customer gets an email with a **Complete your purchase** button and an order summary.
3. When the customer pays, the order is marked as paid and moves to your Shopify **Orders**.

Until then, the order stays a draft. If the customer hasn't paid, open the draft and click **Resend invoice**. If you're taking payment another way, use **Collect payment** to mark it as paid.

To change the email, edit the **Draft order invoice** template at **Settings > Notifications** ([open in the Shopify admin](https://admin.shopify.com/settings/notifications)). See Shopify's guide to [sharing a checkout link with customers](https://help.shopify.com/en/manual/orders/create-orders#share-checkout-link-with-customers).

**Other platforms:**

See the [developer docs](https://docs.sparklayer.io/developers.md).

### Attach your own invoice to an order

Link an invoice file to an order, and customers see **View & Download Invoice** on that order in [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md). Put a [UUID](https://www.uuidgenerator.net/) in the file name or URL so no one can guess it.

**Shopify:**

1. Add an order metafield in Shopify (see [Shopify metafields and data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md)):

   | Item                 | Value                                                                     |
   | -------------------- | ------------------------------------------------------------------------- |
   | **Custom data type** | [Orders](https://admin.shopify.com/settings/custom_data/order/metafields) |
   | **Metafield type**   | `URL` or `File`. One value or a list of values are both supported.        |
   | **Namespace**        | `sparklayer`                                                              |
   | **Key**              | `invoice_url`                                                             |

2. If your invoice isn't hosted anywhere yet, upload it to [Shopify Files](https://admin.shopify.com/content/files?selectedView=all) and click the **Copy link** icon next to it.

3. Open the order in Shopify. In **Metafields**, paste the link into the invoice URL field (for example, **B2B Invoice URL**) and save.

As this is a Shopify metafield, you can attach invoices in bulk, or automatically from a backend system such as an ERP or CRM.

**Other platforms:**

| Item | Value |
| --- | --- |
| **Custom data type** | Orders |
| **Metafield type** | A text string. Use secure, unguessable file names, for example with a [UUID generator](https://www.uuidgenerator.net/). |
| **Namespace** | `sparklayer` |
| **Key** | `invoice_url` |
| **Value** | N/A |

For more information, see the [developer docs](https://docs.sparklayer.io/developers.md).

### Use a third-party invoicing app

For more invoicing features, consider an app such as [Sufio Invoicing](https://docs.sparklayer.io/help/integrations/customer-experience/sufio.md).

## Troubleshooting

**Diagnose: Credit limit or Pay on Account not working?** Check the customer’s credit metafield and group settings.

1. **What’s happening?** Pick the closest match.
   - “Your cart exceeds your available credit limit”: go to question 2
   - Pay on Account doesn’t show at checkout: go to question 3
   - They want to pay part by credit and part by card: go to fix A (One payment method per order)
   - Gift cards don’t work: go to fix B (Gift cards only work at Shopify’s card checkout)
2. **In the customer’s credit metafield, is `balance` what they already owe you?** `balance` is the amount owed, not the credit they have left. Available credit is `credit_limit` minus `balance`. Where to look: Customers > select the customer > Metafields (Shopify admin).
   - Yes: go to question 4
   - No, it’s what they can spend: go to fix C (Set `balance` to what they owe)
3. **Is Pay on Account turned on for the customer’s group?** Payment methods are chosen per customer group. Where to look: Customers > Groups (SparkLayer).
   - Yes: go to fix D (Check the customer’s group)
   - No: go to fix E (Turn on Pay on Account for the group)
4. **Would this order take them over their limit?** For example, with a limit of 250 and a balance of 200, only 50 is available.
   - Yes: go to fix F (The group blocks orders over the limit)
   - No: go to fix G (Everything checks out)

**Fixes**

- **A. One payment method per order** An order can’t be split between Pay on Account and card. The customer can pay the whole order one way.
- **B. Gift cards only work at Shopify’s card checkout** The gift card field is Shopify’s, so it only appears when paying by card. It doesn’t work with Pay on Account, and SparkLayer isn’t a store-credit system.
- **C. Set `balance` to what they owe** To give a customer 250 to spend, use `{"credit_limit":250,"balance":0}`. After a 77.80 order their balance is 77.80, leaving 172.20 available. A balance of 250 means they’ve used it all. Where: Customers > select the customer > Metafields (Shopify admin). See [Credit and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md).
- **D. Check the customer’s group** If the group has Pay on Account but this customer doesn’t see it, check they’re in that group. Next: Wrong prices, payment methods or shipping for a customer?
- **E. Turn on Pay on Account for the group** Add Pay on Account to the group’s payment methods and save. Then set the customer’s credit limit and terms. Where: Customers > Groups (SparkLayer). See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md).
- **F. The group blocks orders over the limit** The customer group is set to block checkout when an order would exceed the limit. Raise the customer’s `credit_limit`, record a payment by lowering their `balance`, or change the group’s credit setting to allow it. Where: Customers > Groups (SparkLayer). See [Block orders over the credit limit](https://docs.sparklayer.io/help/customers/customer-groups.md#block-orders-over-the-credit-limit).
- **G. Everything checks out** Your setup looks right, so we'll take it from here. Send us your answers with the customer’s email and their credit metafield value.

## FAQs

**What happens when a customer goes over their credit limit?**

By default, **Pay on Account** is turned off for that order, and a message asks them to choose another method. To let them order over their limit, see [Let customers order over their credit limit](#let-customers-order-over-their-credit-limit).

**I gave a customer credit, so why can't they pay on account?**

Check the metafield's `balance`. It's what the customer owes you, so a balance equal to the credit limit leaves them nothing to spend. To give them $250 to spend, enter `{"credit_limit":250,"balance":0}`. See [Worked example](#worked-example).

**Why is checkout blocked instead of showing a warning?**

The customer group's **Prevent placing an order if exceeding credit limit** setting is on, which is the default. Turn it off to let customers place the order with a warning instead. See [Let customers order over their credit limit](#let-customers-order-over-their-credit-limit).

**How do I collect payment for a Pay on Account order?**

**Shopify only:**

Pay on Account orders arrive in Shopify as draft orders with payment due later. SparkLayer doesn't take the payment. Collect it your usual way, such as by bank transfer, then mark the order as paid in Shopify. See [Complete a draft order by hand](https://docs.sparklayer.io/help/ordering/automation-and-workflows.md#complete-a-draft-order-by-hand).

**Can a customer pay for one order partly on account and partly by card?**

No. Each order has one payment method, so a customer can't split an order between their credit and a card.

**Can customers use Shopify gift cards or store credit?**

**Shopify only:**

Shopify gift cards only work in Shopify's own checkout, when the customer chooses **Pay Online by Card**. They can't be used with **Pay on Account**. SparkLayer isn't a store credit system: the credit limit is how much a customer can owe you, not a balance they've paid in advance. See [Which payment methods work with the SparkLayer checkout?](https://docs.sparklayer.io/help/ordering/payment-methods.md#which-payment-methods-work-with-the-sparklayer-checkout)

**Can I automatically mark net terms orders as paid?**

Not in SparkLayer: net terms orders arrive with Shopify's payment terms and a due date, and stay unpaid until you collect payment. Use Shopify Flow instead. See [Set net payment terms](#set-net-payment-terms).

**Can customers see payments as well as orders in their balance?**

Yes, with **Payments visibility** (Shopify only). See [Show a real-time account balance](https://docs.sparklayer.io/help/ordering/payment-methods.md#payments---account-balance).


---

# Invoices

URL: https://docs.sparklayer.io/help/ordering/invoices

Turn on SparkLayer Invoices so B2B customers can download PDF invoices from My Account, then add payment details, checkout data and your branding to them.

> **Quick summary**
>
> - SparkLayer Invoices creates a PDF invoice for each B2B order once it reaches **Processing**. Customers and sales agents download it with **View & Download Invoice** on the order in [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md).
> - Turn on **Invoices** at **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app, then add text such as bank details with **Invoice Settings**. To redesign the invoice, use [Templates](#change-the-invoice-design-with-theming).
> - SparkLayer Invoices (automatic PDF invoices, payment reminders and your own invoice template) needs the Growth plan or above. [Net terms and credit limits](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) don't: they're on every plan. 
> - For signed-in B2B customers only, in English, French or Spanish. Invoices can't show line-item tax, refunds, cancellations or part-fulfilled orders.

## How it works

How a SparkLayer invoice is created:

1. **Order placed**: By a B2B customer or a sales agent
2. **Order is Processing**: Draft orders and orders awaiting approval wait until they're completed
3. **Invoice generated**: With your company details, the order's items and your Content Zones
4. **Customer downloads it**: View & Download Invoice on the order in My Account

Each invoice shows:

- Your store name, address, website and phone number, with the order number and invoice date
- The **Bill to** and **Ship to** addresses
- The items (SKU, quantity, unit price and total), subtotal, shipping, tax, total and a tax summary
- Any [Content Zones](#add-payment-details-and-other-text-with-content-zones) you've filled in, at the bottom

[Download Example Invoice (via SparkLayer).pdf](https://docs.sparklayer.io/files/example-invoice.pdf)

Instead of SparkLayer Invoices, you can attach invoices made in another system, send invoices from your store, or use an app such as [Sufio](https://docs.sparklayer.io/help/integrations/customer-experience/sufio.md). See [Choose how to send invoices](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md#choose-how-to-send-invoices).

**Shopify only:**

To compare the ways of invoicing step by step, see the interactive guide [How payments work](https://docs.sparklayer.io/help/guides/how-payments-work.md).

## Turn on invoices

1. Go to **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app.
2. Turn on **Invoices** ("Send invoices to your B2B customers directly from SparkLayer").
3. Click **Save**.

**Invoice Settings** then appears beside **Invoices**, so you can [add your own content](#add-payment-details-and-other-text-with-content-zones). Content changes apply to all invoices, the next time each is viewed.

Invoices are created for orders placed from now on. Orders placed before you turned on Invoices don't get one.

Below Growth, you see a **Growth** badge and an **Unlock** button instead of the switch. **Unlock** shows what Growth adds and starts a free 14-day trial.

## Add payment details and other text with Content Zones

Content Zones are 3 optional blocks of text at the bottom of every invoice. Use them for payment terms, bank details, tax details, terms and conditions or legal statements.

1. Go to **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app and make sure **Invoices** is on.
2. Next to **Invoice Settings**, click **Edit**. The **Edit Invoice Settings** panel opens.
3. For each zone you want, enter a **Title** (up to 50 characters, shown as a bold heading) and **Content** (up to 2,000 characters, shown smaller below it). Line breaks are kept.
4. Save your changes. 

Every zone, title and content box is optional. For example, a zone titled "Making payment" could list the account number, sort code, IBAN, BIC and bank name to pay into.

### Add checkout field data to an invoice

To show details collected at checkout, such as a delivery date from a [custom checkout field](https://docs.sparklayer.io/help/ordering/checkout-fields.md#add-a-custom-checkout-field), paste one of these snippets into a Content Zone's **Content** box.

No coding is needed. You can change plain words such as `Tax ID:`, but leave everything inside `{% %}` and `{{ }}` as it is. Where a snippet names a checkout field (such as `"tax-id"`), it must match the field's name.

**Show "Additional Information" field (e.g. Purchase Order)**

You need the [Additional Information field](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md#set-up-the-additional-information-field-po-number) turned on at checkout first.

```html
{% if purchase.customer_reference %}
Customer Reference: {{ purchase.customer_reference }}
{% endif %}
```

**Show the payment type**

Shows a message based on the [payment method](https://docs.sparklayer.io/help/ordering/payment-methods.md) used for the order.

```html
{% if purchase.payment_method == "upfrontPayment" %}
A message for Pay Online by Card
{% elsif purchase.payment_method == "paymentOnAccount" %}
A message for Payment On Account
{% elsif purchase.payment_method == "paymentByInvoice" %}
A message for Pay By Invoice
{% elsif purchase.payment_method == "quote" %}
A message for Quote
{% else %}
{{ purchase.payment_method }}
{% endif %}
```

**Show the invoice due date**

You need [net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md#set-net-payment-terms) set on the customer's metafield first, so invoices get a due date.

```html
{% if data.purchase.dates.payment_due_at %}
<p>
Due Date: {{ data.purchase.dates.payment_due_at | ldate }}
</p> 
{% endif %}
```

**Show a custom "Shipping date"**

You need a custom "Shipping date" [checkout field](https://docs.sparklayer.io/help/ordering/checkout-fields.md#add-a-custom-checkout-field) first. The `field.name` must match the `name` of your checkout field.

```html
{% for field in purchase.custom_fields %}
{% if field.name == "delivery-date" %}
Shipping Delivery Date: {{ field.value }}
{% endif %}
{% endfor %}
```

**Show a custom "Order Notes"**

You need a custom "Order Notes" [checkout field](https://docs.sparklayer.io/help/ordering/checkout-fields.md#add-a-custom-checkout-field) first. The `field.name` must match the `name` of your checkout field.

```html
{% for field in purchase.custom_fields %}
{% if field.name == "order-notes" %}
Order Notes: {{ field.value }}
{% endif %}
{% endfor %}
```

**Show a custom "Tax ID"**

You need a custom "Tax ID" [checkout field](https://docs.sparklayer.io/help/ordering/checkout-fields.md#add-a-custom-checkout-field) first. The `field.name` must match the `name` of your checkout field.

```html
{% for field in purchase.custom_fields %}
{% if field.name == "tax-id" %}
Tax ID: {{ field.value }}
{% endif %}
{% endfor %}
```

**Show an Accounting ID ("Tax ID") from metafield**

You need the Accounting ID metafield on your store first (see below). It's the only metafield an invoice can show.

| Item | Details |
| --- | --- |
| **Custom data type** | [Customers](https://admin.shopify.com/settings/custom_data/customer/metafields) |
| **Metafield type** | `single line text` |
| **Namespace** | `sparklayer` |
| **Key** | `accounting_id` |
| **Use** | A unique accounting ID for the customer, for example the account ID in your ERP or accounts package. When it's set, it's also added to the order's metadata in your eCommerce platform. |

```html
{% if purchase.customers.sparklayer.accounting_id %}
<p>{{ purchase.customers.sparklayer.accounting_id }}</p>
{% endif %}
```

## Update your company details

Invoices show your company name, address, phone number and website at the top. SparkLayer syncs these from your store, and what you enter here overrides what B2B customers see.

1. Go to **Settings > Configurations > Store** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Store** in the Shopify app.
2. Next to **Store details**, click **Edit**.
3. Update the **Store name**, **Store address**, **Phone number**, **Email** and **Website URL**.
4. Click **Save**.

See [Settings](https://docs.sparklayer.io/help/dashboard/settings.md#store-details).

## Change the invoice design with theming

Theming gives full control of the invoice's layout, fonts, colours and content. Templates use a template language, so we recommend working with a web developer. Invoice templates need the Growth plan or above.

Go to **Settings > Templates** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/theme)), or **SparkLayer Wholesale > Settings > Templates** in the Shopify app and click **Create template**. This creates a template theme for your invoices, email notifications and translations. See [Settings](https://docs.sparklayer.io/help/dashboard/settings.md#templates) and the [templates developer docs](https://docs.sparklayer.io/developers/templates.md).

Example changes:

**Output the product image on an invoice**

In the `<thead>`, add a new `<th>` at the start:

```html
<thead>
<tr>
<th style="width: 10%"></th>
<th style="width: 60%">{{ "pdf.quote.section.line_items.table.headings.item" | t }}</th>
<th style="width: 10%">{{ "pdf.quote.section.line_items.table.headings.quantity" | t }}</th>
<th style="width: 15%" class="text-right">{{ "pdf.quote.section.line_items.table.headings.unit_price" | t }}</th>
<th style="width: 15%" class="text-right">{{ "pdf.quote.section.line_items.table.headings.total" | t }}</th>
</tr>
</thead>
```

In the `<tbody>`, add a new `<td>` at the start:

```html
<td>
<img src="{{ line.image_url }}&height=160" height="80">
</td>
```

**Output a logo on an invoice**

At the start of the template file, find this code:

```html
{% if data.merchant.store_name %}
 <h1>{{ data.merchant.store_name }}</h1>
{% endif %}
```

Host your logo image somewhere, then replace the code with:

```html
{% if data.merchant.store_name %}
 <img src="path-to-your-hosted-image-file" style="width: 200px; height: auto">
{% endif %}
```

## Test your invoices

There's no invoice preview, but changes show the next time an invoice is viewed. To check them:

1. **Place a test order.** Sign in to your store as a B2B customer or sales agent and place an order. It must reach **Processing**, so it can't be a draft order.
2. **Open the order** in My Account.
3. **Click View & Download Invoice.** The invoice opens in your browser, where you can download it.
4. **Make changes** to your [Content Zones](#add-payment-details-and-other-text-with-content-zones), [company details](#update-your-company-details) or [theme](#change-the-invoice-design-with-theming), then view the invoice again.

## Reference

### When invoices are available

| Situation | What happens |
| --- | --- |
| **Order is Processing** | An invoice is created. |
| **Order placed before you turned on Invoices** (old, past or historic orders) | No invoice. Invoices are only created for new orders, not for previous orders. |
| **Draft order, or an order awaiting approval** | No invoice until the order is completed. This includes orders from [company users](https://docs.sparklayer.io/help/customers/company-users.md) that need approval. |
| **Refunded or cancelled order** | No invoice. |
| **Split shipment** (part of the order fulfilled first) | The invoice shows all products on the order. |
| **Editing a completed order** (Processing but not yet fulfilled) | Your changes **don't** appear on the invoice. |
| **Editing a draft order** | Your changes appear once the order is completed (set to Processing). |

### Limitations

| Item | Limitation |
| --- | --- |
| **Line-item tax** | Invoices can't show a tax breakdown for each line. |
| **Refunds, returns, cancellations** | Invoices can't show these order statuses. |
| **Languages** | English, French and Spanish. Invoices are always in your store's default language, even if your store has several. For another language, contact [our support team](https://docs.sparklayer.io/help/support.md). |
| **Part fulfilment** | Part-fulfilled orders aren't supported. The invoice shows all products on the order, whether they've been fulfilled or not. |
| **Customers** | Only signed-in B2B customers set up in SparkLayer can get invoices. |

### Compliance

Every country has its own invoicing rules, from required fields to tax details and legal statements. Add the payment terms, bank details or legal wording you need with [Content Zones](#add-payment-details-and-other-text-with-content-zones).

> **Check your invoices meet local rules**
>
> SparkLayer isn't an accounting or legal service provider, and isn't liable for your invoices meeting local regulations. Ask a professional to check them.

## FAQs

**What SparkLayer plan do I need to be on to enable invoices?**

Growth, Pro or Enterprise. Net terms and credit limits, without SparkLayer Invoices, are on every plan. Change plan at **Plan card** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Plan** in the Shopify app, or click **Unlock** next to **Invoices** to start a free trial. See [SparkLayer plans and pricing](https://www.sparklayer.io/pricing/).

**How do I turn on invoices?**

Turn on **Invoices** at **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app. See [Turn on invoices](#turn-on-invoices).

**How do I view changes I make to invoices?**

Place a test order and download its invoice from My Account. See [Test your invoices](#test-your-invoices).

**How do multiple currencies work?**

Each invoice uses the order's currency, which is based on the customer's location or your store's settings.

**How does tax work on invoices?**

Tax is calculated from the settings in your store. See [Tax and shipping](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md).

**I can't download an invoice. What am I doing wrong?**

- **The order is Processing.** Invoices aren't available before then.
- **The order was placed after you turned on Invoices.** Older orders don't have an invoice.
- **Your browser allows PDFs to download.** Check its settings.

If it still doesn't work, [contact our support team](https://docs.sparklayer.io/help/support.md).

**Can I get invoices for old or past orders?**

No. SparkLayer only creates invoices for new orders, once Invoices is on. It doesn't create them for previous or historic orders, including [imported order history](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#import-order-history-into-sparklayer).

**If I edit an order, will the changes reflect on the invoice?**

Not once the order is completed (Processing). Changes to a draft order appear once it's completed.

**Can I show custom checkout fields on an invoice?**

Yes, for example a tax ID number. See [Add checkout field data to an invoice](#add-checkout-field-data-to-an-invoice).

**How do I set payment terms and how do they show on invoices**

Add them as free text in a [Content Zone](#add-payment-details-and-other-text-with-content-zones), for example a "Making payment" zone with your bank details. To show a due date based on the customer's net terms, see [Show the invoice due date](#show-the-invoice-due-date).

**How do I turn off my other invoicing system?**

For Sufio, in the SparkLayer Dashboard, go to **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app and turn off **Sufio** under **Invoicing**. The Shopify app has no switch: Sufio's **Setup guide** explains how to disconnect it. For any other invoicing app, uninstall it from your store as usual.

**How do I fully customise how the invoice looks?**

Use [theming](#change-the-invoice-design-with-theming) at **Settings > Templates** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/theme)), or **SparkLayer Wholesale > Settings > Templates** in the Shopify app, with a web developer. [Our support team](https://docs.sparklayer.io/help/support.md) can help.

**Can I use my own invoices instead of the invoices from SparkLayer?**

Yes. See [Attach your own invoice to an order](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md#attach-your-own-invoice-to-an-order).

**How does a customer share an invoice?**

They sign in, open the order and download the PDF to share, for example by email.

**Can I use invoices for my regular (non-B2B) customers?**

No. Invoices are only for signed-in B2B customers set up in SparkLayer.

We'd love to hear your feedback on invoices. Email our product team at [product@sparklayer.io](mailto:product@sparklayer.io).


---

# How tax works at checkout

URL: https://docs.sparklayer.io/help/ordering/tax-and-shipping

See how SparkLayer shows net prices and adds tax at checkout, set up tax on Shopify and other platforms, and fix common tax and shipping cost issues.

> **Quick summary**
>
> - SparkLayer shows B2B prices excluding tax (net pricing) unless you turn on **Tax-inclusive prices**. Tax is added at the last step of the checkout.
> - SparkLayer doesn't calculate tax: it uses your eCommerce platform's tax settings. On Shopify, that's **Settings > Taxes and duties** ([open in the Shopify admin](https://admin.shopify.com/settings/taxes)).
> - Most tax options here are for Shopify. Other platforms use their own settings, with the limits in [Set up tax on other platforms](#set-up-tax-on-other-platforms).
> - Shipping is set up separately, at **Settings > Shipping** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping** in the Shopify app. See [Shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md).

## How it works

A B2B price is either net or gross:

| Price type | What it means |
| --- | --- |
| **Net** | The price excludes tax. A $20.00 price is $20.00 before tax. |
| **Gross** | The price includes tax. A $20.00 price already contains the tax. |

By default, SparkLayer shows net prices, whatever tax setting your website uses. Customers see exactly the price in their [price list](https://docs.sparklayer.io/help/pricing/managing-pricing.md): if it has SKU `EEEAR` at 7.99, the product page shows $7.99.

On the **Review & Pay** step, SparkLayer asks your platform for the tax and shows it as its own line: **Sub-total**, **Shipping**, **Tax** and **Total**. Here's how that works with Shopify:

**How tax works with SparkLayer and Shopify**

1. **Your B2B customer browses your store.** All prices shown by SparkLayer exclude tax — customers always see the net price, whatever your Shopify tax settings.
2. **The B2B price comes from your price list.** Customers see the wholesale price from their SparkLayer price list.
3. **Customer goes to checkout.** SparkLayer works with Shopify to calculate the tax to add.
4. **Different tax rates per product?** If our team has enabled this, SparkLayer creates a preliminary Shopify order (tagged `b2b-pending`) when the shipping address is selected to get exact per-product tax. Otherwise tax is calculated as a single rate across the order when checkout completes.
5. **Is the customer tax-exempt?** Tax-exempt customers (Customers › [Customer] › Manage tax exemptions) pay no tax; otherwise Shopify checks "Charge tax on this product" per product.
6. **Tax rate based on shipping country.** Managed in Shopify under Settings › Taxes and duties.
7. **Your wholesale price is sent to Shopify,** replacing the retail price.
8. **Do your Shopify prices include tax?** If yes, manual price lists need no change; for automatic price lists tick "adjust percentage to account for tax". If no, no special setup is needed.
9. **Prices are shown as net + tax,** with tax as a separate line item.
10. **Customer completes their order.** The preliminary draft order is updated, or a new order is created.
11. **The order appears in your Shopify admin.** With "include tax in price" on, Shopify shows tax-inclusive prices with a tax summary — the totals match checkout.

For a step-by-step setup, from checking your store's prices to testing an order, follow the guide [Get B2B tax and VAT right](https://docs.sparklayer.io/help/guides/tax-and-vat.md). This page is the reference for each setting.

### Show prices including tax

To show prices including tax, labelled "inc. tax", turn on **Tax-inclusive prices** at **Settings > Configurations > Pricing and cart** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Pricing and cart** in the Shopify app and on the price lists that need it, and give each product a `display_tax_rate` in your [price CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md), such as `10` for 10% GST. It changes what buyers see, not what they pay. Because the rate comes from a price CSV, it has no effect on automatic price lists. For the steps and limitations, see [Show tax-inclusive prices](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-tax-inclusive-prices).

## Set up tax on Shopify

**Shopify only:**

In Shopify, you set tax rules for the whole store, then make exceptions for customers and products.

Before you start:

- **Check your current tax setup** in **Settings > Taxes and duties** ([open in the Shopify admin](https://admin.shopify.com/settings/taxes)).
- **Read Shopify's guide** to [setting up tax](https://help.shopify.com/en/manual/taxes/registration/setup).
- **Check the effect on retail customers** if your store serves both retail (B2C) and B2B. Many of these settings apply to both.

### Make a customer tax-exempt

**Shopify only:**

A tax-exempt customer still sees net prices, and pays zero tax at checkout.

1. In the Shopify admin, go to **Customers** ([open in the Shopify admin](https://admin.shopify.com/customers)) and open the customer.
2. In the customer's details, click **Manage tax exemptions**.
3. Untick **Collect tax**, then click **Save**.

With a third-party tax app such as Avalara or TaxJar, also mark the customer as exempt in that app. See [Tax is charged but I use a third-party tax app](#tax-is-charged-but-i-use-a-third-party-tax-app-eg-avalara-taxjar).

### Turn tax on or off for a product or variant

**Shopify only:**

1. In the Shopify admin, go to **Products** ([open in the Shopify admin](https://admin.shopify.com/products)) and open the product.
2. In **Pricing**, tick or untick **Charge tax on this product**. When ticked, the product uses your Shopify tax rules.
3. For a single variant, open the variant and tick or untick **Charge tax on this variant** (**Taxable** in newer versions of the Shopify admin).
4. Click **Save**.

Products that don't charge tax are left out of the tax total at checkout.

### Set tax by country

**Shopify only:**

Shopify applies tax rules by the customer's shipping country, at the last step of the checkout.

1. In the Shopify admin, go to **Settings > Taxes and duties** ([open in the Shopify admin](https://admin.shopify.com/settings/taxes)).
2. Under **Regional settings**, check the **Collecting tax** column for each country or region. A region needs a [shipping zone](https://help.shopify.com/en/manual/shipping/setting-up-and-managing-your-shipping) before you can collect tax there.
3. Select a country or region to manage its tax settings.

You can also manage these from **Settings > Markets** ([open in the Shopify admin](https://admin.shopify.com/settings/markets)).

### Remove tax from a draft order

**Shopify only:**

If orders arrive in Shopify as draft orders, you can change the tax before you complete them.

1. In the Shopify admin, open the draft order.
2. Click **Estimated tax**.
3. Untick **Charge taxes**, then click **Apply**.

**Estimated tax** then shows **Not collected** and 0.00. Only the tax total changes, not the product prices.

### Charge different tax rates on different products

**Shopify only:**

By default, tax is charged on the cart subtotal. If your products have different tax rates in one tax jurisdiction, SparkLayer can work out tax per line instead ("line item tax"). Our team turns it on for you.

Line item tax applies when **Include sales tax in product price and shipping rate** is on in Shopify. To check:

1. In the Shopify admin, go to **Settings > Taxes and duties** ([open in the Shopify admin](https://admin.shopify.com/settings/taxes)).
2. Under **Global settings**, see whether **Include sales tax in product price and shipping rate** is ticked.

If it's ticked and your products have different tax rates, [contact our support team](https://docs.sparklayer.io/help/support.md) to turn on line item tax. It's the **Create a draft order on calculate** setting at **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app, which only our team can change. To stop charging tax on some lines, untick **Charge tax** on those variants in Shopify.

> **Draft orders are created before the order is complete**
>
> With line item tax on, SparkLayer creates the Shopify draft order when the customer reaches the shipping and payment step, before they complete the order. The draft is tagged `b2b-pending`, which changes to `b2b` when the customer completes the order.

**Why line item tax is needed**

SparkLayer applies a discount to each line item so the customer pays their B2B price.

| Include sales tax in product price and shipping rate | How SparkLayer calculates the discount |
| --- | --- |
| **Off** | The difference between the Shopify price and the SparkLayer B2B price. |
| **On** | The discount also has to account for tax. Without line item tax, SparkLayer uses one tax rate (the rate of the first line item) for every line. Shopify only gives SparkLayer each line item's tax rate when it creates a draft order. |

For example, two products with the same £6.00 B2B price, one at the default tax rate and one at 5%:

| Product | Shopify price | Without line item tax | With line item tax |
| --- | --- | --- | --- |
| Default tax product | £12.00 | £6.00 (discount £6.00) | £6.00 (discount £6.00) |
| 5% tax product | £10.50 | £6.00 (discount £4.50), incorrect | £5.25 (discount £5.25), correct |

### Adjust automatic price lists for tax-inclusive Shopify prices

**Shopify only:**

If **Include sales tax in product price and shipping rate** is on in Shopify, an [automatic price list](https://docs.sparklayer.io/help/pricing/managing-pricing.md#set-up-automatic-pricing) based on **Shopify Price** takes its percentage off a price that already includes tax. Work out a percentage that also takes the tax out, or customers pay tax twice: see [Tax-inclusive prices](https://docs.sparklayer.io/help/pricing/managing-pricing.md#tax-inclusive-prices). [Manual price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md) don't need this if you upload net prices.

## Set up tax on other platforms

On BigCommerce, Wix, WooCommerce and Magento, SparkLayer uses your platform's tax rules. Set tax up there, then check these limits:

| Platform | Where tax is set up | Limits |
| --- | --- | --- |
| BigCommerce | BigCommerce tax settings | Multi-zone tax only works if prices are entered exclusive of tax, or if tax outside the default zone is set to update product prices. If you change **How are prices displayed on your storefront** on its own, contact us so SparkLayer can resync. See [BigCommerce limitations](https://docs.sparklayer.io/help/platforms/bigcommerce/limitations.md). |
| Wix | **Settings > Tax** in your Wix dashboard ([setup guide](https://docs.sparklayer.io/help/platforms/wix/install.md#adjusting-tax-settings)) | Tax exemptions only apply when the customer pays through the Wix checkout (upfront payment). With manual payment methods, tax is charged. See [Wix limitations](https://docs.sparklayer.io/help/platforms/wix/limitations.md). |
| WooCommerce | WooCommerce tax settings ([setup guide](https://docs.sparklayer.io/help/platforms/woocommerce/install.md#adjusting-tax-settings)) | None documented. |
| Magento | Magento tax settings ([setup guide](https://docs.sparklayer.io/help/platforms/magento/install.md#adjusting-tax-settings)) | None documented. |

**Shopify only:**

On Shopify, orders that mix taxable and tax-exempt products aren't handled, and duties aren't supported. See [Shopify limitations](https://docs.sparklayer.io/help/platforms/shopify/limitations.md).

## Show tax information on your storefront

Change any tax wording in the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) without code at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app: add an override for the key, enter your text and click **Save and publish**. See [Change checkout text](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md#change-checkout-text). A developer can set the same keys in your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting) instead: see [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md).

### Change the word "tax"

These keys set the tax wording in the cart and checkout:

| Key | Default text |
| --- | --- |
| `global.totals.tax` | Tax |
| `cart.tax-shipping-note` | Tax and shipping costs calculated during checkout |
| `cart.tax-shipping-message` | Tax and shipping costs shown on next step |

**Core Script code for your developer**

```javascript title="Core Script"
translations: {
  en: {
    "global.totals.tax": "Tax",
    "cart.tax-shipping-note": "Tax and shipping costs calculated during checkout",
    "cart.tax-shipping-message": "Tax and shipping costs shown on next step"
  }
},
```

### Add a tax note next to prices

Add text such as "Excluding tax: " before the product page price, or "(ex. tax)" after the unit price in the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md), as in "US$6.99 per unit (ex. tax)". Set these keys in **Translation overrides**:

| Key | Example text | Where it shows |
| --- | --- | --- |
| `pdp.price.from-prefix` | Excluding tax: | Before the price on the product page |
| `global.per-unit` | `{price}` per unit (ex. tax) | The unit price in the cart. Keep `{price}`, which is replaced with the price. |

**Core Script code for your developer**

```javascript title="Core Script"
translations: {
  en: {
    "pdp.price.from-prefix": "Excluding tax: ",
    "global.per-unit": "{price} per unit (ex. tax)",
  }
},
```

### Collect a tax ID for international shipping

Some countries require the customer's tax ID (or equivalent) at checkout, so orders comply with local tax law and aren't held up or fined at customs. Collecting it means the order can be processed and converted from a draft to a completed order in Shopify.

Countries that may need a national tax number (such as CPF/CNPJ, RFC or Resident ID) include Brazil, Chile, Colombia, Costa Rica, Ecuador, Guatemala, Indonesia, Italy, Mexico, Malaysia, Peru, Portugal, Paraguay and Turkey. Formats and rules vary, so check the regulations for each destination.

When it's needed, the **Details** step shows an **Additional Tax ID** field above **Additional Information**.

To change the field's label and placeholder, set these keys in **Translation overrides**:

| Key | Default text |
| --- | --- |
| `checkout.notes.tax-id-label` | Additional Tax ID |
| `checkout.notes.tax-id-placeholder` | Tax ID |

**Core Script code for your developer**

```javascript title="Core Script"
translations: {
  en: {
    "checkout.notes.tax-id-label": "Additional Tax ID",
    "checkout.notes.tax-id-placeholder": "Tax ID",
  }
}, 
```

If you already collect a tax ID with a [custom checkout field](https://docs.sparklayer.io/help/ordering/checkout-fields.md), we recommend turning that field off.

## Set up shipping

Use your eCommerce platform's shipping rates, or create B2B shipping methods in SparkLayer at **Settings > Shipping** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping** in the Shopify app. See [Shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md).

## Why is tax charged on shipping?

SparkLayer uses Shopify's tax calculation, so shipping is taxed whenever Shopify taxes it. B2B orders can show tax on shipping even when your retail checkout looks different, for one of these reasons.

| Reason | What happens |
| --- | --- |
| **The customer is in Canada, the EU, the UK or the US** | Shopify charges tax on shipping in these regions whatever its **Charge tax on shipping rates** setting says. Our development team has confirmed this is how Shopify behaves. |
| **Include sales tax in product price and shipping rate is on** | Your Shopify shipping rates already contain tax. SparkLayer shows net amounts, so it has to charge that tax when it creates the order. |

For example, with 20% VAT in the UK:

| Line | Net | VAT at 20% | Total |
| --- | --- | --- | --- |
| Products | £500.00 | £100.00 | £600.00 |
| Shipping | £95.00 | £19.00 | £114.00 |
| **Order** | £595.00 | £119.00 | £714.00 |

The customer sees £95.00 shipping, and £114.00 once VAT is added.

**Shopify only:**

To change this:

- **Use SparkLayer shipping rates**, entered as net values, such as 95 for £95.00 before tax. See [Shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md#set-up-sparklayer-shipping-rules).
- **Make the customer tax-exempt**, where that's right for them, so their order has no tax on products or shipping. See [Make a customer tax-exempt](#make-a-customer-tax-exempt).

## Troubleshooting

These fixes are for Shopify. On other platforms, check your platform's tax settings and [its limits](#set-up-tax-on-other-platforms), or [contact our support team](https://docs.sparklayer.io/help/support.md).

**Diagnose: Prices or tax looking wrong?** Check your Shopify tax settings against your price lists.

1. **What looks wrong?** Pick the closest match.
   - B2B prices are too high, or tax is charged twice: go to question 2
   - Tax is added to shipping in the B2B checkout: go to fix A (Shopify taxes shipping in some regions)
   - I want B2B prices shown including tax: go to fix B (Tax-inclusive display has three parts)
   - VAT or tax is missing at checkout: go to question 3
2. **Is “Include sales tax in product price and shipping rate” turned on?** It’s under Global settings. It decides whether Shopify treats your prices as including tax, which is common for UK, EU and Australian stores. Where to look: Settings > Taxes and duties (Shopify admin).
   - On: go to question 4
   - Off: go to question 5
3. **Is the customer marked as tax exempt in Shopify?** Reverse charge for VAT-registered EU customers uses Shopify’s customer tax exemption. Where to look: Customers > select the customer > Tax settings (Shopify admin).
   - Yes: go to fix C (That’s why tax isn’t added)
   - No: go to fix D (Check the customer’s address and test their checkout)
4. **Which type of price list does the customer use?** Manual lists are uploaded by CSV or set in the Price editor. Automatic lists apply a percentage to your Shopify prices. Where to look: Pricing > Price lists (SparkLayer).
   - Manual (CSV or Price editor): go to question 5
   - Automatic (a percentage): go to question 6
5. **Are the prices in the price list excluding tax (net)?** All SparkLayer prices are net. Tax is added at checkout. Where to look: Pricing > Price editor (SparkLayer).
   - Yes, net: go to fix E (Your tax setup looks right)
   - No, they include tax: go to fix F (Upload your prices excluding tax)
   - Not sure: go to fix G (Compare one product in the Price editor)
6. **Has the list’s percentage been raised to take the tax out too?** An automatic list based on tax-inclusive Shopify prices needs its percentage adjusted for tax. For example, with 20% VAT and a 10% trade discount, use 25% off. Where to look: Pricing > Price lists (SparkLayer).
   - Yes: go to fix E (Your tax setup looks right)
   - No: go to fix H (Adjust the percentage for tax)

**Fixes**

- **A. Shopify taxes shipping in some regions** SparkLayer uses Shopify’s tax calculation. In Canada, the EU, the UK and the US, Shopify charges tax on shipping whatever its “Charge tax on shipping rates” setting says, so the B2B checkout can show tax on shipping. If that’s a problem, use SparkLayer shipping with your rates entered without tax. See [Tax and shipping](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md).
- **B. Tax-inclusive display has three parts** Buyers see gross prices once three things are in place: Tax-inclusive prices turned on for your store (if you don’t see the setting, ask us), the price lists chosen, and a `display_tax_rate` column in the price CSV, for example 10 for Australian GST. It works on manual price lists only, not automatic ones, so use a manual list for those customers. See [Show tax-inclusive prices](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-tax-inclusive-prices).
- **C. That’s why tax isn’t added** Tax-exempt customers check out without tax. Remove the exemption if they should pay it. Where: Customers > select the customer > Tax settings (Shopify admin).
- **D. Check the customer’s address and test their checkout** Tax follows the customer’s default address and your Shopify tax regions. Check their default address, that you collect tax in that country, and that the products are set to charge tax. Then place a test order as the customer. Where: Settings > Taxes and duties (Shopify admin).
- **E. Your tax setup looks right** The SparkLayer checkout shows net prices with tax on its own line. If “Include sales tax” is on, the Shopify order shows tax-inclusive prices instead. The totals are the same: it’s just shown differently.
- **F. Upload your prices excluding tax** Prices that already include tax get tax added again at checkout, so customers pay it twice. Convert them to net prices and upload the list again. Where: Pricing > Price lists (SparkLayer).
- **G. Compare one product in the Price editor** Pick a product, work out its price without tax, and check it matches the Price editor. If it doesn’t, your list includes tax and needs uploading again as net prices. Where: Pricing > Price editor (SparkLayer).
- **H. Adjust the percentage for tax** Without it, the percentage comes off your tax-inclusive Shopify prices, so B2B prices come out too high and tax is added again at checkout. Where: Pricing > Price lists (SparkLayer). See [Adjust automatic price lists for tax](https://docs.sparklayer.io/help/pricing/managing-pricing.md#tax-inclusive-prices).

**Tax is charged when it shouldn't be**

**Shopify only:**

If the customer should be tax-exempt, open them in **Customers** ([open in the Shopify admin](https://admin.shopify.com/customers)), click **Manage tax exemptions** and untick **Collect tax**. With a third-party tax app, also see the next question.

**Tax is charged but I use a third-party tax app (e.g. Avalara, TaxJar)**

**Shopify only:**

Tax apps such as Avalara and TaxJar override Shopify's tax settings, so a customer set to "Don't collect tax" in Shopify can still be charged. SparkLayer only passes through the tax that Shopify and your tax app return, so the cause is almost always the tax app's setup. Exempt the customer in both places:

1. In your tax app, add the customer to its exemption list. For example, in Avalara, go to the Exemption Customer List and add the customer with their Shopify customer ID as the Customer Code.
2. In Shopify, open the customer in **Customers** ([open in the Shopify admin](https://admin.shopify.com/customers)), click **Manage tax exemptions** and check that **Collect tax** is unticked.

The two exemptions work independently, so if either is missing, tax may still be charged. For help in your tax app, see its documentation or support team.

**Tax isn't charged when it should be**

**Shopify only:**

Check the customer isn't tax-exempt: open them in **Customers** ([open in the Shopify admin](https://admin.shopify.com/customers)), click **Manage tax exemptions** and make sure **Collect tax** is ticked.

**Prices on the Shopify order don't match the SparkLayer checkout**

**Shopify only:**

1. In **Settings > Taxes and duties** ([open in the Shopify admin](https://admin.shopify.com/settings/taxes)), check whether **Include sales tax in product price and shipping rate** is on. If it is, check each automatic price list's percentage allows for tax: see [Tax-inclusive prices](https://docs.sparklayer.io/help/pricing/managing-pricing.md#tax-inclusive-prices).
2. Check the SparkLayer price is lower than the Shopify price. Go to **Pricing > Price editor** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/editor)), or **SparkLayer Wholesale > Pricing > Price editor** in the Shopify app, search for the variant SKU and note its price in each price list, then compare it with the product's **Price** in Shopify.
3. If **Include sales tax in product price and shipping rate** is on, a difference of a few cents is expected. Shopify only accepts whole-cent unit prices on a draft order, and with this setting on, the unit price has to include tax. For example, $14.45 plus 10% GST is $15.895, so the unit price is sent as $15.90. Shopify multiplies that by the quantity, so 30 units come to $0.15 more than the net sub-total plus 10%. No setting in SparkLayer or Shopify changes this, and line item tax doesn't affect it. If your invoices must match to the cent, add an order discount for the difference to the draft order before you invoice it.

If the Shopify price is lower, the checkout uses it. This includes tax: if the SparkLayer price after tax is higher than your tax-inclusive Shopify price, the checkout also uses the Shopify price.

**Tax is wrong when shipping to a different country**

**Shopify only:**

In **Settings > Taxes and duties** ([open in the Shopify admin](https://admin.shopify.com/settings/taxes)), find the customer's country and check whether you're collecting tax there.

**Tax is charged twice**

- **Manual price lists use net prices.** Upload [manual price list](https://docs.sparklayer.io/help/pricing/managing-pricing.md) prices excluding tax, so tax is added correctly at checkout.
- **Automatic price lists allow for tax.** If **Include sales tax in product price and shipping rate** is on in Shopify, an [automatic price list](https://docs.sparklayer.io/help/pricing/managing-pricing.md)'s percentage must also take out tax. See [Tax-inclusive prices](https://docs.sparklayer.io/help/pricing/managing-pricing.md#tax-inclusive-prices).

**Some products should be taxed and others not**

**Shopify only:**

[Contact our support team](https://docs.sparklayer.io/help/support.md) to turn on line item tax, then untick **Charge tax** on the variants that shouldn't be taxed. See [Charge different tax rates on different products](#charge-different-tax-rates-on-different-products).

**Shipping costs don't match the SparkLayer shipping rules**

With [SparkLayer shipping rates](https://docs.sparklayer.io/help/ordering/shipping-rules.md), the costs at **Settings > Shipping** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping** in the Shopify app should always match the checkout. If they don't, [contact our support team](https://docs.sparklayer.io/help/support.md).

**Can I show gross (tax-inclusive) prices to B2B customers?**

Yes. Turn on **Tax-inclusive prices** at **Settings > Configurations > Pricing and cart** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Pricing and cart** in the Shopify app and add a `display_tax_rate` column to your pricing CSV. Buyers see gross prices, labelled "inc. tax", but pay the same. It only works on manual price lists: see [Show tax-inclusive prices](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-tax-inclusive-prices), including its limitations.

If that doesn't suit your tax setup, try one of these:

| To show | Workaround |
| --- | --- |
| **Net and gross prices** | Show an extra price to signed-in customers with custom theme code, for example from [metafields](https://docs.sparklayer.io/developers/data/metafields.md) on Shopify or BigCommerce. Or use the [RRP (MSRP) feature](https://docs.sparklayer.io/help/pricing/pricing-display.md) to set a price separate from the B2B price. |
| **Gross prices only** | Make the customer tax-exempt in Shopify so their orders are zero-rated, and upload gross amounts to their price lists (though tax isn't technically included). Report on tax afterwards, for example in your accounting system. |


---

# Shipping rules

URL: https://docs.sparklayer.io/help/ordering/shipping-rules

Use your store's shipping rates or SparkLayer's own B2B shipping methods, with bands by order total or weight for each customer group, and pre-select a method.

> **Quick summary**
>
> - By default, B2B customers see your eCommerce platform's shipping methods at checkout in the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md).
> - To create B2B-only methods priced by customer group, order total or weight, tick **Use SparkLayer shipping rates** at **Settings > Shipping** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping** in the Shopify app. On Shopify, **Automatic shipping selection** there sets the pre-selected method.
> - SparkLayer shipping rates need the Starter plan or above (see [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md)). On BigCommerce, they only work with card payment turned off. On Wix, also turn on SparkLayer Shipping in your Wix dashboard.

> **Shopify shipping or SparkLayer shipping: pick one**
>
> B2B customers get one or the other, never both. **Use SparkLayer shipping rates** at **Settings > Shipping** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping** in the Shopify app decides: unticked, they see your store's shipping (on Shopify, Shopify shipping); ticked, they only see your SparkLayer shipping methods.
>
> | Choose                  | You get                                                                                            | Keep in mind                                                                                                                                                                                                                              |
> | ----------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
> | **Shopify shipping**    | Live (calculated) carrier rates and Shopify shipping apps pass through to the SparkLayer checkout. | B2B customers see the same rates as retail. For different automated rates for wholesale, use a shipping app that sets rates by customer tag. See [Show B2B-only shipping methods on Shopify](#show-b2b-only-shipping-methods-on-shopify). |
> | **SparkLayer shipping** | B2B-only methods for each country and customer group, priced by order value or weight.             | One cost per band (the weight or value only picks the band), with no live carrier rates and no rules by product or tag. See [What SparkLayer shipping rules can do](#what-sparklayer-shipping-rules-can-do).                              |

## How it works

How a customer gets a shipping cost:

1. **Add products**: The customer builds their order in the cart.
2. **Choose an address**: On the Details step, they pick a shipping address.
3. **Choose a method**: On Review & Pay, they see the methods for their country (and customer group, with SparkLayer rules).
4. **See the total**: The shipping cost and tax are added to the order total.

Shipping methods come from one of two places:

| Option | Best for | Limits |
| --- | --- | --- |
| **Your store's shipping methods** (default) | Keeping shipping in your platform's admin, and complex rules such as country or state-level rates. Works with third-party shipping apps. | Your platform may need an app for B2B-only shipping methods. |
| **SparkLayer shipping rates** | Different B2B rates for each customer group, especially when retail (DTC) and B2B share one store. Rates by order value or weight. | Basic shipping types only. Managed in SparkLayer, not your platform's shipping admin. |

## Use your store's shipping methods

SparkLayer shows your eCommerce platform's shipping methods and rates out of the box, with nothing to configure.

**Shopify only:**

On Shopify, live shipping rates and shipping rule apps also work: SparkLayer pulls their rates through. **Shopify shipping settings** at **Settings > Shipping** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping** in the Shopify app opens Shopify's **Shipping and delivery** settings. For help, see Shopify's [guide to setting up shipping](https://help.shopify.com/en/manual/shipping/setting-up-and-managing-your-shipping) or contact Shopify support.

### Show B2B-only shipping methods on Shopify

**Shopify only:**

Shopify can't show different shipping methods to different types of customer on its own. Use a shipping app that sets rates by customer tag, such as [Intuitive Shipping](https://docs.sparklayer.io/help/integrations/customer-experience/intuitive-shipping.md), or [SparkLayer shipping rates](#set-up-sparklayer-shipping-rules), which are B2B-only by design.

![Intuitive Shipping logo](https://docs.sparklayer.io/images/help/ordering/shipping-rules/shipping-rules-3c0a2b.webp)

With Intuitive Shipping, you set rates and rules by customer tag, so a signed-in B2B customer (tagged `b2b`) gets their B2B shipping methods. For its full rates to load in SparkLayer, [contact us](https://docs.sparklayer.io/help/support.md) to turn on a setting. See [Features we turn on for you](https://docs.sparklayer.io/help/dashboard/features-on-request.md).

Some other shipping apps also need a setting turned on by our team, and some lower-cost apps don't work with the SparkLayer checkout. Before you buy a shipping app, [ask our support team](https://docs.sparklayer.io/help/support.md) whether it's compatible.

### Choose which method is pre-selected (Shopify)

**Shopify only:**

SparkLayer pre-selects one of your Shopify shipping methods at checkout. Customers can pick another, and their choice is never overridden. To choose which one:

1. Go to **Settings > Shipping > Automatic shipping selection** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping > Automatic shipping selection** in the Shopify app.
2. Choose an option, then click **Save**.

| Option | What's pre-selected |
| --- | --- |
| **First available method (default)** | Whichever method Shopify returns first, whatever its price. If a free rate comes back first, free shipping is the default. |
| **Prefer cheapest paid method** | The lowest-priced method that isn't free, so a free rate doesn't become the default. If every method is free, the first one is used. |

### Change shipping costs after an order is placed on Shopify

**Shopify only:**

Draft orders let customers pick a standard Shopify shipping method while you adjust the cost before completing the order. **Pay on Account** and **Pay by Invoice** orders arrive as drafts unless you [complete drafts automatically](https://docs.sparklayer.io/help/ordering/automation-and-workflows.md).

1. In the Shopify admin, open the draft order and edit its shipping.
2. In **Edit shipping**, choose another rate, or choose **Custom** and enter a **Rate name** and **Price**.
3. Click **Done**.

See Shopify's guide to [adding shipping to an order](https://help.shopify.com/en/manual/orders/create-orders#add-shipping).

### Offer local pickup on Shopify

**Shopify only:**

SparkLayer doesn't support Shopify's **Local pickup** delivery option. Instead, create a normal shipping method called "Local pickup", for example with a zero rate, in **Settings > Shipping and delivery** ([open in the Shopify admin](https://admin.shopify.com/settings/shipping)). It then appears in the SparkLayer checkout.

This method also shows to retail (DTC) customers in the Shopify checkout, unless an app hides it. To show it only to B2B customers, create it as a [SparkLayer shipping method](#set-up-sparklayer-shipping-rules) instead.

## Set up SparkLayer shipping rules

SparkLayer shipping rates have two parts:

| Part | What it is |
| --- | --- |
| **Shipping method** | What the customer sees and picks at checkout, such as "Standard Shipping". Each method applies to chosen countries and customer groups. |
| **Shipping band** | A cost rule inside a method. For example, orders under £100 cost £20 to ship, and orders over £100 ship free. A method without a band doesn't show at checkout. |

Copy the rates from your eCommerce platform or backend system, so customers see the same costs everywhere. For example, if UK customers get free shipping over £100, set up the same rule here.

### What SparkLayer shipping rules can do

SparkLayer shipping rules can:

- Offer B2B-only methods in chosen countries (and, for some countries, states or regions) to chosen customer groups.
- Pick a band by the order's net total or its weight.
- Charge each band's cost: free, a fixed price, a percentage of the net total, or a message instead of a cost.

They can't:

- Charge by the kilogram. A band's price is fixed for the band, and the order's weight only picks the band. For example, a £10 band from 0 to 5,000 g costs £10 for a 1 kg order and for a 5 kg order.
- Set rates by product, product tag or collection.
- Fetch live carrier rates.

For any of these, use your store's shipping with a shipping app instead. See [Show B2B-only shipping methods on Shopify](#show-b2b-only-shipping-methods-on-shopify).

### Turn on SparkLayer shipping rates

1. Go to **Settings > Shipping** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping** in the Shopify app.
2. Under **Shipping rates**, tick **Use SparkLayer shipping rates** ("Set B2B-only shipping methods, priced by customer group, order total or weight").
3. Click **Save**.

The **Shipping methods** card appears, listing each method's **Countries**, **Customer groups** ("All groups" when none are chosen), number of **Bands** and **Priority**. To go back to your store's own rates, untick the box.

Some platforms need an extra step:

| Platform | What to do |
| --- | --- |
| **Wix** | In your Wix dashboard, go to **Settings > Shipping, Delivery & Fulfillment**. Make sure you have at least one shipping region, click **Manage Your Apps** below it, and turn on **SparkLayer Shipping**. See [Install SparkLayer on Wix](https://docs.sparklayer.io/help/platforms/wix/install.md#enabling-sparklayer-shipping-methods). |
| **BigCommerce** | Turn off card payment (**Card at checkout** in your customer groups). BigCommerce overwrites the shipping method on orders paid by card in its checkout. See [BigCommerce limitations](https://docs.sparklayer.io/help/platforms/bigcommerce/limitations.md). |
| **Shopify, WooCommerce, Magento** | Nothing extra. |

#### If you set up shipping during a trial

Shipping methods and bands you set up during a trial can stay live at checkout after you move to the free plan, while their settings become locked so you can't change them. To switch them off, [contact our support team](https://docs.sparklayer.io/help/support.md).

### Create a shipping method

1. At **Settings > Shipping** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping** in the Shopify app, click **Create shipping method**.
2. Fill in the fields below, then click **Save**. Add bands once the method is saved.

| Field | What it does |
| --- | --- |
| **Method name** | The name customers see at checkout, such as "Standard Shipping" or "Next Day". Make it clear. |
| **Shipping SKU** | A unique ID for the method, such as `standard-shipping`, filled in from the name. If you use the SparkLayer API, it must match the shipping SKU in your backend system, such as your ERP. |
| **Priority order** | The order methods are shown in. 1 shows first at checkout. Set this on every method. |
| **Available countries** | The countries where the method is offered at checkout. Choose at least one. |
| **States or regions (optional)** | For the United States, Canada and Australia, limit the method to states or regions, for example "California, New York". Leave it empty for the whole country. |
| **Customer groups** | The B2B customer groups that see the method. Leave every group unticked to offer it to all B2B customers. |

To delete a method, open it and choose **More actions** > **Delete method**. It disappears from checkout; orders already placed keep their shipping.

### Add shipping bands

Shipping bands set a method's cost, by **Order total (net)** or **Order weight (grams)**. Weight bands always use grams, so convert from oz or lb if your products use them.

1. Open the shipping method and, under **Shipping bands**, click **Add band**.
2. Fill in the fields below, then click **Add band**.
3. Add more bands to cover the rest of your order values or weights.

| Field | What it does |
| --- | --- |
| **Band name** | A name such as "Orders under £99". Customers don't see it, except in a custom message key. |
| **Shipping SKU (optional)** | A shipping SKU for the band, if your backend system supports band SKUs. If you leave it blank, the method's SKU is used. |
| **Cost type** | **Free**, **Fixed price**, **Percentage of the net total**, or **Custom message** (see [Show a message instead of a cost](#show-a-message-instead-of-a-cost)). |
| **Cost** | The price, or the percentage for a percentage band. Ignored for free and custom message bands. |
| **Applies based on** | **Order total (net)** or **Order weight (grams)**. |
| **From** and **Up to (optional)** | The range the band covers. Leave **Up to** empty for "and over". To apply a band to every order, set **From** to 0 and leave **Up to** empty. |

Band order sets each band's priority. At checkout, the first band the order matches sets the cost, so a free shipping band only applies if no band above it also matches the order. Make sure the bands cover every order value or weight with no gaps: an order whose weight falls in a gap gets no rate from this method.

**Example: £20 under £99, free above**

Add a band with **Cost type** **Fixed price**, **Cost** 20, **Applies based on** **Order total (net)**, **From** 0 and **Up to** 98.99. Then add a **Free** band from 99 with no **Up to**.

To change a band, click **Edit** next to it. **Remove** deletes it: orders it covered fall to the next matching band, or the method won't show for them.

### Show a message instead of a cost

Use the **Custom message** cost type when you can't confirm the cost yet. At checkout, the method shows a message such as "To be confirmed" instead of a cost. The order's shipping cost is set to 0.00, so you can edit it afterwards.

1. Add or edit a band and set **Cost type** to **Custom message**, then save it.
2. In the **Shipping bands** table, the band's **Cost** shows its key, `shipping.custom-message.` followed by the band's name in lowercase with dashes, for example `shipping.custom-message.orders-under-250`. Copy it.
3. Go to **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app, click **Add override**, choose the key and enter your message, such as "To be confirmed".
4. Click **Save and publish**.

For more on translation overrides, see [Change checkout text](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md#change-checkout-text).

**Core Script code for your developer**

A developer can set the message in your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting) translations instead (see [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md)):

```javascript title="Core Script"
/* Replace orders-under-250 with your band's key */
translations: {
  en: {
    "shipping.custom-message.orders-under-250": "To be confirmed",
  }
},
```

### Test your shipping rates

Your methods show in the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) and on **Review & Pay**, such as **Standard Shipping** £20.00 and **Express Shipping** £50.00. Try different countries, customer groups, order values and weights to check the right methods and costs show.

## Set a custom shipping rate as a sales agent

With [Sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md), a sales agent whose [role](https://docs.sparklayer.io/help/sales-reps/roles.md) has the **Change shipping** permission, such as the built-in **Sales administrator**, can set a custom shipping rate at checkout. It overrides your shipping rules.

## Troubleshooting

**Diagnose: Shipping not working as expected?** Check which shipping your B2B customers use.

1. **Is “Use SparkLayer shipping rates” ticked?** For B2B customers it’s either your Shopify shipping or SparkLayer’s shipping rules, never both. Where to look: Settings > Shipping (SparkLayer).
   - Yes, SparkLayer shipping: go to question 2
   - No, Shopify shipping: go to question 3
2. **What’s wrong?** Pick the closest match.
   - I want live carrier rates: go to fix A (Live rates come from Shopify shipping)
   - Rates should depend on the products: go to fix B (Product-based rates need a shipping app)
   - Free shipping isn’t applied: go to question 4
   - “No shipping methods available” at checkout: go to fix C (Cover the customer’s country and group)
   - I can’t edit my rates after a trial: go to fix D (Ask us to switch them off)
3. **What’s wrong?** Pick the closest match.
   - B2B customers see the same rates as retail: go to fix E (Use a shipping app that sets rates by customer tag)
   - I want to hide free shipping from B2B: go to fix E (Use a shipping app that sets rates by customer tag)
   - B2B customers see wrong or missing rates: go to fix F (Check the customer’s setup)
4. **Is the free shipping a SparkLayer discount?** Free shipping can come from a shipping band or from a discount. Where to look: Pricing > Discounts (SparkLayer).
   - Yes, a discount: go to fix G (Select every shipping method the customer can see)
   - No, a shipping band: go to fix H (Check the band order)

**Fixes**

- **A. Live rates come from Shopify shipping** SparkLayer’s rules charge per band, chosen by order value or weight. For live or calculated carrier rates, untick “Use SparkLayer shipping rates” so B2B customers get your Shopify rates, including shipping apps. Where: Settings > Shipping (SparkLayer). See [Shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md).
- **B. Product-based rates need a shipping app** SparkLayer’s rules work on order value or weight only, not on products or tags. Use Shopify shipping with an app that sets rates by product or customer tag, such as Intuitive Shipping. See [Intuitive Shipping](https://docs.sparklayer.io/help/integrations/customer-experience/intuitive-shipping.md).
- **C. Cover the customer’s country and group** No band matches this customer. Check your shipping rules cover their country, their customer group and the order’s value or weight. Where: Settings > Shipping (SparkLayer).
- **D. Ask us to switch them off** Shipping rules set up during a trial can stay live after a downgrade while the settings are locked. Tell us and we’ll switch SparkLayer shipping off, so your Shopify rates apply.
- **E. Use a shipping app that sets rates by customer tag** Shopify can’t show different rates to different customers on its own. A shipping app that uses customer tags, such as Intuitive Shipping, can. Some apps, including Intuitive Shipping, also need a SparkLayer setting: follow the app’s guide, or tell us which app you use. See [Intuitive Shipping](https://docs.sparklayer.io/help/integrations/customer-experience/intuitive-shipping.md).
- **F. Check the customer’s setup** If one customer sees the wrong rates, check their tags and group. Next: Wrong prices, payment methods or shipping for a customer?
- **G. Select every shipping method the customer can see** A free shipping discount only applies to the shipping methods it names. If you have methods per region, select each one, or make a discount per region. Also check the customer’s group is eligible and the threshold is in their price list’s currency. Where: Pricing > Discounts (SparkLayer). See [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md).
- **H. Check the band order** The first band an order matches sets its cost, so a free band only applies if no band above it also matches. Put the free band first, or make the bands cover separate ranges. Where: Settings > Shipping (SparkLayer). See [Free shipping isn’t applied](https://docs.sparklayer.io/help/ordering/shipping-rules.md#free-shipping-isnt-applied).

**Free shipping isn't applied, or the wrong rate shows**

Change your bands so the free shipping band is the first one the order matches. At checkout, the first band the order matches sets the cost. If a paid band higher up also covers the order, its rate wins, even when the order qualifies for free shipping.

1. Open the shipping method at **Settings > Shipping** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping** in the Shopify app.
2. Check the order of the bands, and which ones cover the order's total or weight.
3. Edit the ranges so they don't overlap, or reorder the bands so the free band comes first.

Then [test your shipping rates](#test-your-shipping-rates) with an order that should ship free.

**Local pickup not displaying**

**Shopify only:**

SparkLayer doesn't support Shopify's Local pickup option. Create a free "Local pickup" shipping method in Shopify or SparkLayer, whichever you use (see [Offer local pickup on Shopify](#offer-local-pickup-on-shopify)), and check it's available for the region you're testing.

**Shipping costs don't match the shipping bands**

- **The expected condition:** the bands use weight or order value as you expect.
- **Product data:** all products have a valid weight and price, so the bands can be calculated.

If the costs at checkout still differ from the bands at **Settings > Shipping** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping** in the Shopify app, [contact our support team](https://docs.sparklayer.io/help/support.md).

**Having technical issues?**

If you see error messages or can't set this up, see [Troubleshooting](https://docs.sparklayer.io/help/troubleshooting.md) or [contact our support team](https://docs.sparklayer.io/help/support.md).


---

# Set up quotes

URL: https://docs.sparklayer.io/help/ordering/quoting

Set up the SparkLayer Quoting Engine so B2B customers can request quotes from their cart: turn it on, prepare your sales team, statuses, emails and groups.

> **Quick summary**
>
> - The Quoting Engine lets B2B customers submit their cart as a [quote](https://docs.sparklayer.io/help/glossary.md#quote) instead of checking out. Your sales team reviews, edits and discusses it, then the customer or a sales agent confirms it as an order.
> - Turn on **Quotes** at **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app, then choose which groups can request quotes at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app.
> - Included on Pro and Enterprise, and a $49 per month add-on on Starter and Growth. It isn't on Basic, because reviewing quotes needs a sales agent or Sales administrator, and sales agents start on Starter. It also needs SparkLayer version 3.7 or above.
> - Quotes live in SparkLayer, not as Shopify draft orders. For reviewing, editing and completing quotes, see [Work on a quote](https://docs.sparklayer.io/help/ordering/work-on-a-quote.md).

## How it works

A customer submits their cart as a quote. Your team is emailed, a Sales administrator assigns it to a sales agent, and the agent and customer agree the details on the quote's timeline. The customer, or the agent for them, then confirms it and it becomes an order. Each step is in [How a quote becomes an order](https://docs.sparklayer.io/help/ordering/work-on-a-quote.md#how-a-quote-becomes-an-order).

| Use it for | How |
| --- | --- |
| **Negotiation** | Agree price or terms before an order is placed. |
| **Pre-orders** | Customers request a quote ahead of time. |
| **Sales-assisted orders** | Your team adds products to a quote that the customer can change before they finalise it. |
| **Price on application (POA)** | Customers add items to a quote before the price is set. |

Quote statuses control what customers can do at each stage, such as edit or complete the quote, and whether it's archived when it expires. Each quote's timeline records messages, internal notes and edits, and key events send [email notifications](#email-notifications-sent).

Try the [interactive demo](https://www.figma.com/proto/EImqog20F76HKgwXPGG6hG/SparkLayer-Quoting?page-id=0%3A1\&node-id=0-4591\&viewport=1497%2C630%2C0.15\&t=PxY0LmnWuGO5gszG-1\&scaling=min-zoom\&content-scaling=fixed\&starting-point-node-id=0%3A2882) of the Quoting Engine.

## Turn on the Quoting Engine

Before you start:

- **SparkLayer version 3.7 or above**: the [Core Script](https://docs.sparklayer.io/help/glossary.md#core-script) version in your theme. Check **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. To upgrade, see [Frontend integration](https://docs.sparklayer.io/developers/frontend.md) or ask your developer.
- **The Pro or Enterprise plan, or the Quoting Engine add-on on Starter or Growth.** The add-on is $49 per month (see [Add-ons](https://docs.sparklayer.io/help/plans-and-features.md#add-ons)). Without either, **Quotes** shows a **Pro** badge and an **Unlock** button, which shows what Pro adds and starts a free 14-day trial. Or change plan at **Plan card** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Plan** in the Shopify app. See [SparkLayer plans and pricing](https://www.sparklayer.io/pricing/).
- **A sales agent who can review quotes.** See [Set up your sales team for quoting](#set-up-your-sales-team-for-quoting).

1. Go to **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app.
2. Turn on **Quotes** ("Customers request quotes from their cart and you reply with prices"). The **Quote statuses** row appears.
3. Click **Save**.
4. Set up your [quote statuses](#set-up-quote-statuses) and [purchase notifications](#choose-who-is-notified-about-quotes). Set up notifications before you launch quoting.
5. [Choose which customer groups can request quotes](#choose-which-customer-groups-can-request-quotes).

> **Request for Quote is replaced**
>
> If your store still offers the **Request for Quote** payment method, customers stop seeing it at checkout once you turn on **Quotes**.

## Set up your sales team for quoting

[Sales agents](https://docs.sparklayer.io/help/sales-ordering.md) review quotes by signing in on the customer's behalf. A sales agent is anyone in your business who places orders for customers. Their role at **Sales Agents > Roles** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/roles)), or **SparkLayer Wholesale > Sales agents > Roles** in the Shopify app sets their access:

| Role | What they can do with quotes |
| --- | --- |
| **Sales administrator** | Everything a sales agent can do, plus assign quotes to sales agents and other higher-level tasks. |
| **Sales agent** | Review, edit, message and complete the quotes assigned to them. |

Without a sales team, set up one account with the **Sales administrator** role. Someone must be able to sign in on a customer's behalf to review their quotes. What they do day to day is in [Work on a quote](https://docs.sparklayer.io/help/ordering/work-on-a-quote.md).

## Set up quote statuses

Quote statuses group your quotes and set the rules for each stage. For example, stop customers editing a quote while you review it, or archive quotes when they expire.

There are 2 statuses to start with: **Quote Requested**, where every new quote starts (marked **Default**), and **Awaiting Customer**, for when a sales agent is waiting on the customer. See [What happens at each status](https://docs.sparklayer.io/help/ordering/work-on-a-quote.md#what-happens-at-each-status).

1. Go to **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app.
2. Next to **Quote statuses**, click **Edit**. The **Quote statuses** window lists your statuses, with **Default** beside the one new quotes start in.
3. To add a status, enter it in **New status** (such as "Awaiting approval") and click **Add status**. To delete one, click **Remove**. You can't remove the default status.
4. Click **Done**.

**Status settings**

Each status also has these settings.

| Setting | What it does |
| --- | --- |
| **Quote Status Display Name** | The status customers see when viewing the quote in My Account. Up to 45 characters. |
| **Quote Status Handle (or ID)** | Identifies the status internally. Up to 45 characters. |
| **Set as default quote status for customers** | All new quotes start in this status. |
| **What status should the quote move to when an edit is made?** | The status a quote moves to automatically when the customer or a sales agent edits it. Choose **No change in status** to keep it the same. |
| **Allow customers to complete quote** | Customers can complete the quote and place their order. |
| **Allow customers to make edits to quote** | Customers can change the quote. |
| **Require an expiry date before changing to a new status** | A sales agent must set an expiry date before moving the quote out of this status. |
| **Archive quote once quote has expired** | After the expiry date, the quote is cancelled and can't be changed. Customers need to start a new quote. |

The last 4 settings are under **Actions allowed in this status**.

Statuses appear on quotes in My Account. Only sales agents assigned to a quote can change its status.

## Choose who is notified about quotes

Quote emails go to:

| Recipient | When |
| --- | --- |
| **The assigned sales agent** | Once a Sales administrator assigns them a quote, they get all its notifications, at their email address in [Sales rep setup](https://docs.sparklayer.io/help/sales-reps.md). |
| **Additional email addresses** | For quotes with no assigned sales agent, such as new quotes, if you've added addresses in **Purchase notifications**. |
| **Your store email (fallback)** | If no sales agent is assigned and no additional addresses are set up. |

To email extra addresses about unassigned quotes:

1. Go to **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app.
2. Next to **Purchase notifications**, click **Edit**. Until you add someone, it says "No one is emailed when quotes and orders update."
3. In **Email addresses**, enter the addresses, separated with commas.
4. Click **Save**.

This covers new quotes, and quotes and orders that become unassigned.

**Where the fallback store email comes from**

It's your eCommerce platform's store email. On Shopify, it's the **Store email** at **Settings > General** ([open in the Shopify admin](https://admin.shopify.com/settings/general)), in your store profile, where your standard Shopify notifications usually go. For other platforms, see the [developer docs](https://docs.sparklayer.io/developers.md).

## Choose which customer groups can request quotes

1. 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 click the group's name. For every group, click **Edit** on the base customer group.
2. Under **Inherited rules**, click **+ Override** next to **Quoting engine** (on the base group, **+ Customize**), then **Configure**.
3. Tick **Allow quotes to be submitted**, then click **Save**.

Customers in the group then see **Request Quote** beside **Checkout** in their cart. Click **Reset** on the rule to hand it back to the base customer group. See [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md#let-customers-request-quotes).

To make a group quote-only, also override its **Checkout access** rule so customers can't check out. See [Disable checkout](https://docs.sparklayer.io/help/customers/customer-groups.md#disable-checkout).

## Let customers open quotes from email links

To make links in quote emails open the quote or order details directly, turn on My Account quick links. See [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md).

## Change the quote text

Change this text without code at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app. See [Change checkout text](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md#change-checkout-text) and [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md).

| Key | Default text |
| --- | --- |
| `pdp.messaging.poa` | POA |
| `cart.request-quote` | Request Quote |
| `cart.edit-quote` | Edit Quote |
| `cart.checkout.confirm-btn.quote` | Submit Quote: `{total}` |
| `account.order-view.quote` | View & Download Quote |
| `account.order-view.edit-quote` | Edit Quote |
| `account.order-view.confirm-and-complete` | Confirm & Complete |
| `account.order-view.cancel-and-archive` | Cancel and archive. |
| `account.order-view.redirect-to-checkout` | You'll be redirected to the checkout to edit or complete your order. |
| `account.order-view.quote-not-required` | No longer require this quote? |

`cart.request-quote` is the button in the cart, and `cart.checkout.confirm-btn.quote` is the last button of the quote checkout, where `{total}` is replaced with the quote total. 

**Core Script code for your developer**

A developer can set the same text in your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting):

```javascript title="Core Script"
translations: {
  en: {
    "pdp.messaging.poa": "POA",
    "cart.request-quote": "Request Quote",
    "cart.edit-quote": "Edit Quote",
    "cart.checkout.confirm-btn.quote": "Submit Quote: {total}",
    "account.order-view.quote": "View & Download Quote",
    "account.order-view.edit-quote": "Edit Quote",
    "account.order-view.confirm-and-complete": "Confirm & Complete",
    "account.order-view.cancel-and-archive": "Cancel and archive.",
    "account.order-view.redirect-to-checkout": "You'll be redirected to the checkout to edit or complete your order.",
    "account.order-view.quote-not-required": "No longer require this quote?",
  },
},
```

The text of quote emails and the quote PDF comes from your [templates](https://docs.sparklayer.io/help/dashboard/settings.md#templates). See [Email notifications](#email-notifications-sent).

## Reference

### Features

**Every Quoting Engine feature**

| Area | What you can do |
| --- | --- |
| **Configuration** | Show or hide quoting for each customer group. Email your sales team when a new quote arrives. |
| **Workflow** | Assign a quote to a sales agent. Set a status on each quote, choose a default status, and set rules for each status: whether the customer can edit or complete the quote, whether they can download a PDF, and whether an expiry date is required. |
| **Ordering** | Add custom line items, custom shipping, unavailable or POA (price on application) products and out-of-stock products to a quote. If a custom shipping rate isn't added to the total, see [this FAQ](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#custom-shipping-rate-not-in-total). Set the payment method on the quote, for the customer to use when they complete it. |
| **PDF** | Download the quote as a PDF, and theme and customise the PDF. |
| **Expiry** | Set quotes to expire after a date. |
| **Timeline and communications** | Send messages to the customer, save internal notes all sales agents can see, track changes to the quote, and send email notifications when the quote changes or a message arrives. |

For what each quote action does and what the timeline records, see [Work on a quote](https://docs.sparklayer.io/help/ordering/work-on-a-quote.md#reference).

### Limitations

| Item | Limitation |
| --- | --- |
| **Company users** | [Limited users](https://docs.sparklayer.io/help/customers/company-users.md) can't request quotes. |
| **Discounts** | You can't add discounts to a quote. |

**BigCommerce only:**

**Out-of-stock products:** on BigCommerce, you can't add out-of-stock products when a quote is created or edited.

## Email notifications

Change these emails with a template at **Settings > Templates** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/theme)), or **SparkLayer Wholesale > Settings > Templates** in the Shopify app: see [Settings](https://docs.sparklayer.io/help/dashboard/settings.md#templates). Turn on [My Account quick links](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) so each email's link opens the quote directly.

**Quote management and communication emails** are sent on creation, assignment, messages and updates.

**New quote notification (sent to merchant)**

**Trigger:** Sent when an end-customer requests a new quote

**Recipient:** Sales administrator (and any emails added in **Purchase notifications**)

**Template**: `Emails/new-quote-notification-to-merchant`

> **Email Subject:**
>
> \[Company name] has requested a new quote \[#Pxxxx]
>
> **Email Copy:**
>
> \[Customer name] has requested a new quote \[#Pxxxx].
>
> To review, approve, or amend the details, please click the button below.
>
> **Button:** \[View requested quote]

**New quote assigned (sent to Sales Agent)**

**Trigger:** Sent when a quote is assigned to a Sales Agent

**Recipient:** Sales Agent

**Template**: `Emails/quote-assigned-notification-to-agent`

> **Email Subject:** \[Sales Admin name] has assigned you a quote for \[Company name] \[#Pxxxx]
>
> **Email Copy:** A quote for \[Customer name] has been assigned to you by \[Sales Admin name]. Assigned on \[Date] with Quote ID \[#Pxxxx].
>
> **Button:** \[View assigned quote]

**First response from Sales Agent to quote request (sent to end-customer)**

**Trigger:** Sent when a Sales Agent sends their first reply on a new quote

**Recipient:** End-customer

**Template**: `Emails/quote-request-responded-to-notification-to-customer`

> **Email Subject:** \[Sales Agent name] has responded to your quote request \[#Pxxxx]
>
> **Email Copy:** \[Sales Agent name] from \[Merchant name] has responded to your quote request \[#Pxxxx].
>
> **Customer Message:** xxxxx
>
> **Email Copy:** To access the full conversation in your account and reply, click below.
>
> **Button:** \[View quote and conversation]

**Subsequent quote update from Sales Agent (sent to end-customer)**

**Trigger:** Sent when a Sales Agent updates an existing quote (price, quantities, products, etc)

**Recipient:** End-customer

**Template**: `Emails/quote-updated-notification-to-customer`

> **Email Subject:** \[Sales Agent name] has updated your quote \[#Pxxxx]
>
> **Email Copy:** \[Sales Agent name] from \[Merchant name] has updated your quote \[#Pxxxx].
>
> **Customer Message:** xxxxx
>
> **Email Copy:** To access the full conversation in your account and reply, click below.
>
> **Button:** \[View quote and conversation]

**Quote sent to end-customer by Sales Agent**

**Trigger:** Sent when a Sales Agent creates a quote and sends it to the customer

**Recipient:** End-customer

**Template**: `Emails/quote-created-notification-to-customer`

> **Email Subject:** \[Sales Agent name] has sent a quote to review \[#Pxxxx]
>
> **Email Copy:** \[Sales Agent name] from \[Merchant name] has created a new quote for you to review \[#Pxxxx].
>
> **Customer Message:** xxxxx
>
> **Email Copy:** To access the full conversation in your account and reply, click below.
>
> **Button:** \[View quote and conversation]

**Timeline - message sent by Sales Agent to end-customer**

**Trigger:** Sent to a customer when a sales agent leaves a note

**Recipient:** End-customer

**Template**: `Emails/purchase-history-message-notification-to-customer`

> **Email Subject:** \[Sales Agent name] has sent you a message about your quote \[#Pxxxx]
>
> **Email Copy:** \[Sales Agent name] from \[Merchant name] has sent you a new message about your quote \[#Pxxxx].
>
> **Customer Message:** xxxxx
>
> **Email Copy:** To access the full conversation in your account and reply, click below.
>
> **Button:** \[View quote and conversation]

**Timeline - message sent by end-customer to Sales Agent**

**Trigger:** Sent to a Sales Agent when a customer leaves a note

**Recipient:** Sales Agent

**Template**: `Emails/purchase-history-message-notification-to-agent`

> **Email Subject:** \[Company name] has sent you a message about their quote \[#Pxxxx]
>
> **Email Copy:** \[Customer name] from \[Company name] has sent a new message about their quote \[#Pxxxx].
>
> **Customer Message:** xxxxxx
>
> **Email Copy:** To access the full conversation in your account and reply, click below.
>
> **Button:** \[View quote and conversation]

**Limited user approval flow emails** are sent when a [limited user](https://docs.sparklayer.io/help/glossary.md#limited-user) submits an order for approval, and when it's approved.

**Limited user order submitted for approval (sent to merchant)**

**Trigger:** Sent when a limited user (end-customer) submits an order created from a quote for approval

**Recipient:** Main company user (merchant) / approver

**Template**: `Emails/limited-user-purchase-review`

> **Email Subject:** \[Limited User name] has submitted a new order for your review \[#Pxxxx]
>
> **Email Copy:** \[Limited User name], a limited user on your account, has requested to place order \[#Pxxxx].
>
> As a main user, your approval is required before the order can be processed.
>
> To review and approve or amend the details, please click the button below:
>
> **Button:** \[Review Order]

**Limited user order approved (sent to end-customer)**

**Trigger:** Sent when a main company user (merchant) approves an order submitted by a limited user

**Recipient:** Limited user (end-customer)

**Template**: `Emails/limited-user-purchase-approved`

> **Email Subject:** Your order \[#Pxxxx] has been approved by \[Main User name]
>
> **Email Copy:** Your order \[#Pxxxx] for \[Company name] has been approved by \[Main User name] and will now be processed for shipment. For any questions, please contact \[Main User name].To access the full conversation in your account and reply, click below.
>
> **Button:** \[View Approved Order]

## FAQs

For problems with a quote itself, such as **Confirm & Complete** being greyed out, see [Troubleshooting](https://docs.sparklayer.io/help/ordering/work-on-a-quote.md#troubleshooting) in Work on a quote.

**Can I restrict which customer groups can request quotes?**

Yes. See [Choose which customer groups can request quotes](#choose-which-customer-groups-can-request-quotes).

**Do I need to have sales agents to use the Quoting Engine?**

You don't need a sales team, but someone must be able to sign in on a customer's behalf to review quotes. Give them the **Sales administrator** role: see [Sales rep setup](https://docs.sparklayer.io/help/sales-reps.md). This is why quotes aren't available on Basic: sales agents start on Starter.

**How do I edit the email notifications sent?**

With your templates (see [Email notifications](#email-notifications-sent)). For help, [contact our team](https://docs.sparklayer.io/help/support.md).

**Can I use "Request for Quote" as a payment method alongside this?**

No. Once you turn on **Quotes**, customers no longer see Request for Quote at checkout.

**Does the Quoting Engine create a draft order in Shopify?**

**Shopify only:**

No. Quotes live in SparkLayer. A confirmed quote becomes a regular Shopify order in your usual workflow.

We'd love to hear your feedback on the Quoting Engine. Email our product team at [product@sparklayer.io](mailto:product@sparklayer.io).


---

# Work on a quote

URL: https://docs.sparklayer.io/help/ordering/work-on-a-quote

Review, assign, edit and message B2B quotes as a sales agent or Sales administrator, then complete them, and see how a quote moves from request to order.

> **Quick summary**
>
> - For the people who handle quotes from the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md): sales agents and Sales administrators. You work on a quote by signing in to your store on the customer's behalf, where it opens in their My Account.
> - A Sales administrator assigns each new quote to a sales agent, with a status and an expiry date. Only the assigned sales agent can then change it.
> - You find quotes in the new quote email and in **Recent Activity** in your account on the storefront, where you review and edit them. Each quote has a purchase ID such as `P#1264`.
> - Once you've agreed it, the customer, or a sales agent for them, clicks **Confirm & Complete** and the quote becomes an order.

To turn on quotes, set up statuses and choose who's emailed, see [Set up quotes](https://docs.sparklayer.io/help/ordering/quoting.md).

## How a quote becomes an order

How a quote moves from request to order:

1. **Requested**: The customer submits their cart as a quote and chooses a shipping method
2. **Assigned**: Your team is emailed; a Sales administrator assigns a sales agent, a status and an expiry date
3. **Negotiated**: The agent and customer edit the quote and exchange messages on its timeline
4. **Confirmed**: The customer, or the agent for them, clicks Confirm & Complete and places the order
5. **Order**: The order is Processing and follows your usual workflow until it ships

The quote's [status](#what-happens-at-each-status) decides what the customer can do at each stage, such as edit or complete it. On Shopify, a completed quote becomes a regular order, not a draft order.

If a [limited user](https://docs.sparklayer.io/help/customers/company-users.md) completes a quote, the order goes to their company's main user for approval first. Once it's approved, it reaches you as a normal order. See [Approve orders from limited users](https://docs.sparklayer.io/help/customers/company-users.md#approve-orders-from-limited-users).

### Where to find quotes

| Where | What you see |
| --- | --- |
| **Email** | A new quote email with the customer's details and the items, and a **View requested quote** button. Who gets it is set in [Choose who is notified about quotes](https://docs.sparklayer.io/help/ordering/quoting.md#choose-who-is-notified-about-quotes). |
| **Your account on the storefront** | Sales agents find quotes in **Recent Activity**, with **All**, **Assigned to me** and **Placed by me** tabs. The **Status** column tells quotes (such as "Quote Requested") apart from orders. |
| **Orders** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/activity)), or **SparkLayer Wholesale > Orders** in the Shopify app | Quotes may also be listed here as **Awaiting merchant**, with their purchase ID, as there's no order in your store yet. To work on a quote, open it on the storefront. See [Orders](https://docs.sparklayer.io/help/dashboard/orders.md) and [Awaiting merchant](https://docs.sparklayer.io/help/glossary.md#awaiting-merchant). |

## Request a quote

Customers, or sales agents signed in on their behalf, request a quote from the cart: they click **Request Quote** instead of **Checkout** (sales agents see **Submit Quote**), choose a shipping method and click **Submit Quote**. No payment is taken. For each step of the quote checkout, see [Submit a quote instead](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md#submit-a-quote-instead).

The quote then shows in the activity list in the customer's [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md). Its **Summary** shows when it was requested, its expiry date, the assigned sales agent and its status. The **Order Lines**, **Timeline** and **Files** tabs show the products, messages and attachments, and **Download PDF** downloads a copy.

### Start a quote for a customer

Sales agents can build a quote for a customer: sign in as them with [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#submit-a-quote), add the products and submit the cart as a quote. The customer is emailed to review it.

**Shopify only:**

Don't create a draft order for a B2B customer by hand in the Shopify admin instead: it uses your Shopify prices, not the customer's B2B prices. To order or quote at their prices, use [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md).

## What happens at each status

| Status | Who acts next | What the customer sees and can do |
| --- | --- | --- |
| **Quote Requested** (default) | You. A Sales administrator assigns the quote, and the sales agent reviews it, adjusting prices, quantities or shipping. | The quote in My Account, with this status. **Confirm & Complete** is disabled by design, so the order can't be placed until you've reviewed it. They can message you on the quote's timeline. |
| **Awaiting Customer** | The customer. | They review your changes, then click **Confirm & Complete** to place the order. They can also click **Edit Quote** if the status allows edits. |
| Statuses you add | Whoever you decide. | Whatever the status allows, with **Allow customers to complete quote** and **Allow customers to make edits to quote**. |

Only sales agents assigned to a quote can change its status. To add statuses or change what each allows, see [Set up quote statuses](https://docs.sparklayer.io/help/ordering/quoting.md#set-up-quote-statuses).

## Review and assign a quote

1. Click **View requested quote** in the new quote email and sign in to your store. The quote opens in the customer's My Account.
2. As a Sales administrator, click the edit icon in the yellow box at the top of the quote and set:
   - **Assigned Sales Agent**: who handles the quote
   - **Quote Status**: one of your [quote statuses](#what-happens-at-each-status)
   - **Expiry Date**: after this, the customer must start a new quote (if the status archives expired quotes)
3. Click **Save**. The assigned sales agent is emailed, and sees the quote when they next sign in.

Of your team, only the sales agent assigned to the quote can change it.

## Edit a quote and send it back

Sales agents can edit a quote, and so can customers if its status allows.

1. Open the quote in My Account and click **Edit Quote**. It opens in the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md).
2. Make your changes. Customers can add or remove products and change quantities. Sales agents can also change line prices and shipping, add custom line items and custom shipping, and add out-of-stock (not on BigCommerce) or POA (price on application) products.
3. Continue through the checkout. Sales agents get an extra **Quote Details** step, with a banner naming the customer. There, they:
   - Set the **Quote Status**, **Expiry Date** and **Assigned Sales Agent**
   - Under **Communications**, choose **Notify customer** (emails the customer) or **Save as internal note**, with an optional message
4. Click **Submit Revisions to Quote**. The customer is notified to review the changes.

Changing prices and shipping needs the **Change quoted prices** and **Change shipping** permissions in the sales agent's [role](https://docs.sparklayer.io/help/sales-reps/roles.md). You can't add discounts to a quote.

## Message the customer about a quote

Each quote's **Timeline** tab in My Account keeps all messages between the customer and your sales team in one place. Messages are also sent by email.

| Who | How they send a message |
| --- | --- |
| **Sales agent** | Choose **Notify customer** and click **Send Email**, or choose **Save as internal note** for a private note (in a yellow box, seen only by sales agents). Customers sign in to reply. |
| **Customer** | Types in the message box and clicks **Send Message**. The assigned sales agent is notified. |

Each entry shows who sent it and when, for example "Seb Latch (Customer) sent a message". See [Order timeline and messages](https://docs.sparklayer.io/help/customers/timeline.md).

## Complete a quote

Once the quote is agreed, the customer or a sales agent turns it into an order.

1. Open the quote in My Account and click **Confirm & Complete**.
2. The checkout opens at **Review & Pay**, with a banner saying "You are completing a quote" and the quote's shipping method selected. Choose a payment method, and change anything else you need. 
3. Tick the terms and conditions and click **Complete Order**.

The quote becomes a **Processing** order and follows your usual workflow until it ships. On Shopify, it's a regular order, not a draft.

If the quote is no longer needed, click **Cancel and archive** under the quote's buttons. This cancels it and stops any further changes.

## Reference

### Quote actions

| Action | Customer | Sales agent |
| --- | --- | --- |
| **Edit Quote** | Opens the quote in the cart to add or remove products and change quantities, if the status allows edits. | Opens the quote in the cart to also change line prices and shipping costs. |
| **Confirm & Complete** | Goes to checkout to place the order, if the status allows it. The shipping method is pre-selected and can be changed; they choose how to pay. | Completes the quote on the customer's behalf. |
| **Cancel and archive** | Cancels the quote and stops any further changes. Only use it when the quote is no longer needed. | The same. |

### Timeline activities

| Activity | What's shown |
| --- | --- |
| **Quote actions** | When the quote was requested and updated |
| **Customer messages** | Messages from the customer |
| **Sales agent messages** | Messages from a sales agent |
| **Internal notes** | Private notes from a sales agent |
| **Quote edits** | Each edit, with a log of what changed |

The emails sent at each step are listed in [Email notifications](https://docs.sparklayer.io/help/ordering/quoting.md#email-notifications-sent).

## Troubleshooting

**Diagnose: Quote buttons greyed out?** Check who acts next and what each status allows.

1. **Who can’t act on the quote?** Buyers and merchants see different buttons at each stage.
   - The customer: go to question 2
   - Me or a sales agent: go to question 3
2. **Is the quote’s status “Quote requested”?** That’s the status right after a customer asks for a quote.
   - Yes: go to fix A (You review the quote first)
   - No: go to question 4
3. **Does the person’s role allow them to work on quotes?** Sales agents can only do what their role allows. Where to look: Sales Agents > Roles (SparkLayer).
   - Yes: go to question 5
   - No / not sure: go to fix B (Give the role quote permissions)
4. **Is the customer trying to edit the quote?** Whether a customer can edit a quote is set for each status.
   - Yes: go to fix C (Allow editing for that status)
   - No: go to fix D (Everything checks out)
5. **Are your quote statuses turned on?** Quote statuses and what each allows are set in your configuration. Where to look: Settings > Configurations > Quote statuses (SparkLayer).
   - Yes: go to fix D (Everything checks out)
   - No / not sure: go to fix E (Turn on your quote statuses)

**Fixes**

- **A. You review the quote first** When a customer requests a quote, you or a sales agent review it and adjust prices. Confirm & complete stays greyed out for the customer until you move it on. That’s by design. See [Quoting](https://docs.sparklayer.io/help/ordering/quoting.md).
- **B. Give the role quote permissions** Edit the person’s role, tick the quote permissions and save. Where: Sales Agents > Roles (SparkLayer).
- **C. Allow editing for that status** Open Quote statuses, edit the status the quote is in, and allow the customer to edit it. Where: Settings > Configurations > Quote statuses (SparkLayer).
- **D. Everything checks out** Your setup looks right, so we'll take it from here. Send us your answers with the quote number and who’s trying to act on it.
- **E. Turn on your quote statuses** Enable the quote statuses you use, then reload the quote. Where: Settings > Configurations > Quote statuses (SparkLayer).

## FAQs

**Why is Confirm & Complete greyed out?**

| Who | Why |
| --- | --- |
| **The customer**, at **Quote Requested** | This is by design. You review the quote first, then move it to a status that lets the customer complete it, such as **Awaiting Customer**. See [What happens at each status](#what-happens-at-each-status). |
| **The customer**, at another status | The status doesn't allow customers to complete quotes. Check its **Allow customers to complete quote** setting in [quote statuses](https://docs.sparklayer.io/help/ordering/quoting.md#set-up-quote-statuses). |
| **You or a sales agent** | The agent's [role](https://docs.sparklayer.io/help/sales-reps/roles.md#permissions) doesn't have the **Quotes** permission they need, such as **Edit quotes** or **Complete quotes**, or the quote isn't assigned to them. Only the assigned sales agent can change a quote. Also check the quote's status allows the action. |

**Can I edit the prices and shipping costs on a quote?**

Yes, if your sales agent [role](https://docs.sparklayer.io/help/sales-reps/roles.md) has the **Change quoted prices** and **Change shipping** permissions. The built-in **Sales administrator** role has both.

**Can I apply discounts to a quote?**

No. Change the line prices instead.


---

# Shopping lists

URL: https://docs.sparklayer.io/help/ordering/shopping-lists

Let B2B customers save named shopping lists, add products from the cart or product page, edit quantities, add whole lists to the cart and export them to CSV.

> **Quick summary**
>
> - Shopping lists let B2B customers save products and quantities in named lists, such as "Every month order", then add a whole list to the cart to reorder.
> - They're on by default, on every plan, with nothing to set up. Customers use them from **My Account > Shopping Lists**, product pages and the cart. Sales agents can use and export lists when [ordering for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md).
> - To hide them, turn off **Shopping lists** at **Storefront > Options > My Account** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > My Account** in the Shopify app.

## How it works

Shopping lists save products with their variants and quantities, so customers don't rebuild the same order each time. Each customer can keep as many lists as they need, such as monthly restocks, seasonal ranges or an order built up over several days.

How customers use shopping lists:

1. **Save products**: From a product page, the cart or My Account.
2. **Edit the list**: Change quantities, add or remove products.
3. **Add to cart**: The whole list, or only selected items.
4. **Check out**: As with any other order.

To try them, sign in to our [B2B demo store](https://demo.sparklayer.io/pages/b2b-login-register).

[Favourites](https://docs.sparklayer.io/help/ordering/favourites.md) are different: they save only the product, with no variant or quantity. See [Favourites vs shopping lists](https://docs.sparklayer.io/help/ordering/favourites.md#favourites-vs-shopping-lists).

## Create a shopping list

Customers can create a list in 3 places:

| Where | How |
| --- | --- |
| **My Account** | Go to **My Account > Shopping Lists** and click **Create List**. This starts an empty list and leaves the cart as it is. |
| **Add to shopping list window** | When adding a product to a list, click **Or create a new shopping list**. |
| **Cart** | Click **Actions**, choose **Add to shopping list**, then create a new list. |

The **Shopping Lists** page shows each list's **Name** and **Last Updated** date, with a search box and an **Actions** menu for each list.

## Add products to a list

**From a product page**

1. Set the quantity of each product or variant you want.
2. Click the **Add to shopping list** icon (a clipboard) next to the **Add to Cart** button.
3. In the **Add to shopping list** window, choose a list (or create a new one) and click **Save**.

The quantity on the page is saved to the list, and a message confirms it.

**From the cart**

1. In the cart, click **Actions**.
2. Choose **Add to shopping list**, or one of the lists shown under **Shopping Lists** in the menu.
3. In the **Add to shopping list** window, choose the list and click **Save**.

## Edit a list

Open a list from **My Account > Shopping Lists**. It shows when it was created and last modified, and each product's quantity and price.

| To | Do this |
| --- | --- |
| **Add products** | Search by name, SKU or barcode at the top of the list, and set the quantity. |
| **Change quantities** | Use the quantity controls on each product. Quantity rules such as pack sizes still apply. |
| **Remove products** | Click the bin icon on a product, or tick several products and remove them together. |

## Add a list to the cart

Customers open the list and add the **whole list** at its saved quantities, or tick products and add **only the selected items**. Then they check out as normal.

Lists top up the cart: if a product is already there, its quantity increases. Nothing in the cart is removed or replaced.

## Export a list to CSV

Customers and sales agents can download a list as a CSV file, to share or work on offline. Unsaved changes are saved first, so the file matches the screen. 

The CSV includes the SKU, name, unit price and quantity of every item. 

## Turn shopping lists off

1. Go to **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app and open **My Account**.
2. Turn off **Shopping lists**.
3. Click **Save and publish**.

The shopping list icon disappears from product pages, and Shopping Lists disappears from My Account.

## FAQs

**Can a customer create more than one shopping list?**

Yes. Customers can create and name as many lists as they need.

**Can products be added to a list without going to the account area?**

Yes. Products can be added straight from a product page or from the cart.

**Does adding a list to the cart replace what's already there?**

No. Items are added to the current cart, and a product already there has its quantity increased.

**Are quantities saved with a list?**

Yes. Each item's quantity is saved and carries over to the cart.

**Can a customer remove items from a list?**

Yes. Items can be removed one at a time or several at once.

**Can a list be downloaded?**

Yes. Customers and sales agents can export any list as a CSV. See [Export a list to CSV](#export-a-list-to-csv).


---

# Favourites

URL: https://docs.sparklayer.io/help/ordering/favourites

Let B2B customers save products with a heart icon as they browse and add them to the cart from My Account, and see how Favourites differ from shopping lists.

> **Quick summary**
>
> - Favourites let B2B customers save a product with one click on the heart icon, then find it in **My Account > Favourites**. They save the product only, not a variant or quantity: for those, use [shopping lists](https://docs.sparklayer.io/help/ordering/shopping-lists.md).
> - They're on by default and need Core Script version 4.9 or later. Check **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.
> - To hide them, turn off **Favourites lists** at **Storefront > Options > My Account** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > My Account** in the Shopify app.

## How it works

Favourites let customers browsing a large catalogue mark products for later, without building an order or filling the cart. When they're ready to buy, they pick the variant and quantity and add the product to the cart.

Each customer sees only their own Favourites, which aren't shared with other users or accounts. There's nothing for you to keep up to date.

To try them, sign in to our [B2B demo store](https://demo.sparklayer.io/).

Before you start:

- **Core Script 4.9 or later** on your storefront. Check **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.
- **Favourites lists turned on** at **Storefront > Options > My Account** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > My Account** in the Shopify app (on by default).

### Favourites vs shopping lists

Favourites and [shopping lists](https://docs.sparklayer.io/help/ordering/shopping-lists.md) work side by side but do different jobs.

| Topic | Favourites | Shopping lists |
| --- | --- | --- |
| **Best for** | Marking products to come back to later | Building and reordering a specific order |
| **What's saved** | The product only | Products with their variants and quantities |
| **Structure** | One simple list per customer | Multiple named lists per customer |
| **Adding to the cart** | Select products, then choose options and quantities | Add the whole list, or selected items, with saved quantities |

A shopping list suits a customer who knows what to reorder. Favourites are quicker for remembering products while browsing.

## Add a product to Favourites

Customers click the heart icon (**Add to favourites**) next to **Add to cart** and the shopping list icon on a product page, or on a product card on a collection page. The heart changes to show the product is saved. Saving it again doesn't create a duplicate.

## View Favourites in My Account

The My Account overview shows the most recently saved products in **Favourites**, above the shopping lists. Hovering over a product shows its name, and **View all** opens the Favourites page.

The Favourites page lists every saved product with its image, name and SKU, with the total in the heading. If nothing's saved yet, it explains how to use the heart icon.

## Add favourites to the cart

1. On the Favourites page, click **Select & add to cart**.
2. Select one or more products.
3. For each product, click **Choose options** to pick the variant and set the quantity. Current pricing and stock are shown for each option.
4. Add the selected products to the cart.

The products stay in Favourites. The usual availability and quantity rules apply, and if a product can't be added, such as when it's no longer available, a message explains why.

## Remove a favourite

On the Favourites page, customers click the remove icon next to a product. It's removed straight away, without changing the product or any shopping lists.

## Turn Favourites off

1. Go to **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app and open **My Account**.
2. Turn off **Favourites lists**.
3. Click **Save and publish**.

The heart icon disappears from product and collection pages, and Favourites disappears from My Account. Turn it back on in the same place at any time.

## FAQs

**What's the difference between Favourites and shopping lists?**

Favourites save only the product, to come back to later. Shopping lists save products with variants and quantities, for building and reordering a specific order. Both are in My Account. See [Favourites vs shopping lists](#favourites-vs-shopping-lists).

**Can a customer save a specific variant or quantity as a favourite?**

No. Customers choose the variant and quantity when adding a favourite to the cart, so they always see current options, pricing and stock.

**Can customers favourite products from collection pages?**

Yes. The heart icon is on collection page product cards as well as product pages.

**Are Favourites shared with other users or accounts?**

No. Favourites are personal to each signed-in customer.

**Does adding a favourite to the cart remove it from Favourites?**

No. Products stay in Favourites after they're added to the cart.

**What happens if a favourited product is no longer available?**

It stays in Favourites but can't be added to the cart. A message explains this, and the customer can remove it.

**Does removing a favourite affect shopping lists?**

No. It only affects that customer's Favourites.

**The heart icon doesn't appear on my store**

Check the requirements in [Before you start](#how-it-works): Core Script 4.9 or later, and **Favourites lists** turned on at **Storefront > Options > My Account** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > My Account** in the Shopify app.

## Next steps

- [Shopping lists](https://docs.sparklayer.io/help/ordering/shopping-lists.md): Save products with their variants and quantities to reorder in one go
- [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md): Everything customers can do in My Account, Favourites included


---

# Intelligent Cart (AI)

URL: https://docs.sparklayer.io/help/ordering/intelligent-cart

Build B2B orders with SparkLayer Intelligent Cart by uploading a PDF, spreadsheet or photo, forwarding an email or scanning barcodes to fill the cart.

> **Quick summary**
>
> - Intelligent Cart uses AI to fill the cart from a file or email listing products and quantities, such as an invoice, purchase order or photo of a handwritten order. Customers can also scan barcodes with their camera.
> - Customers and sales agents use it in the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md), with **Upload a file**, **Forward an email** and **Scan barcode**.
> - The AI features and camera scanning are on the Starter plan and above (see [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md)), and need the latest version of the [Core Script](https://docs.sparklayer.io/help/glossary.md#core-script) in your theme. Importing a CSV file or spreadsheet of SKUs, and using a handheld barcode scanner, work on every plan.
> - Uploaded and emailed data is never used for training, and is deleted within 24 hours.

## How it works

How Intelligent Cart builds a cart:

1. **Send the order**: Upload a file, forward an email or scan a barcode.
2. **AI reads it**: SKUs, barcodes and quantities are picked out.
3. **Products matched**: Only products that match your store are added.
4. **Review and check out**: Edit the cart as normal, then check out or request a quote.

| Feature | What it does | Plan |
| --- | --- | --- |
| **Upload a file** (AI) | Reads documents, spreadsheets and images: PDF, XLSX, PNG, JPG, CSV, TXT, JSON and DOCX. Recognised SKUs and quantities are added to the active cart. | Starter and above |
| **Forward an email** (AI) | Reads order details in the body or an attachment of a forwarded email, and fills the cart. | Starter and above |
| **Scan barcode** | Adds products by scanning their barcodes with a phone or computer camera. | Starter and above |
| [CSV import](#import-products-from-a-csv-file) | Adds products from a file with SKU (or barcode) and quantity columns, or rows pasted from a spreadsheet. | Every plan |
| [Barcode scanner](#use-a-barcode-scanner) | A handheld scanner types each barcode into the cart's search box, like a keyboard. | Every plan |

To try it, sign in to our [demo store](https://demo.sparklayer.io/pages/b2b-login-register).

## Set up Intelligent Cart

- **The latest version of SparkLayer** on your storefront. See the [frontend integration guide](https://docs.sparklayer.io/developers/frontend.md) for how to upgrade, or ask your developer.
- **The Starter plan or above.** See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
- **Barcodes on your products**, if you want barcode scanning. Add them in your eCommerce platform's admin. See [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md) for how barcodes show on your store.

To check it, sign in to your store as a B2B customer and open the cart. An empty cart shows shortcuts to **Upload a file**, **Forward an email**, **Scan barcode** and **Repeat order**. Once it has items, they're in the **Actions** menu next to the search box.

## Build a cart from a file

1. In the cart, click **Upload a file** (in the **Actions** menu once the cart has items).
2. Drop the file onto **Build a cart from a file**, or click **browse** and choose it. 
3. Within a few seconds, SKUs and quantities that match products in your store are added to the cart. Others aren't added.
4. Edit the cart if needed, then check out as normal.

For best results, use a file with SKUs or barcodes, such as an invoice or purchase order. From a previous invoice, for example, Intelligent Cart picks up each item's SKU and quantity.

The items are added to what's already in the cart. 

## Import products from a CSV file

Customers can add many products at once from a CSV file, by uploading it or by pasting rows from a spreadsheet. This works on every plan. 

1. In the cart, open **Actions** and choose **Upload a file**.
2. Drop the CSV file onto the upload box, or click **Paste rows**, paste the first two columns from a spreadsheet and add them.

Under the upload box, customers can download a **SKU template** or a **barcode template** to start from. By default, the file needs two columns with these headings:

| Ordering by | Columns |
| --- | --- |
| SKU | `sku` and `qty` |
| Barcode | `barcode` and `qty` |

```csv
sku,qty
abc123,10
xyz123,20
```

The products in the file are added to the cart. If a product must be ordered in packs, the quantity is rounded up to the nearest valid pack size.

### Rename the CSV column headings

You can give the columns names that suit your customers, for example `Item No.` and `Quantity` instead of `sku` and `qty`. The upload screen then shows your headings.

To do it without code, add translation overrides for these keys at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app.

**For developers: set them in the Core Script**

Add these [text overrides](https://docs.sparklayer.io/help/storefront/languages-and-international.md) to your Core Script and change the values:

```javascript title="Core Script"
translations: {
  en: {
    "cart.import.csv-headers.sku": "Item No.",
    "cart.import.csv-headers.barcode": "Barcode No.",
    "cart.import.csv-headers.qty": "Quantity",
  }
}, 
```

## Build a cart from an email

1. In the cart, click **Forward an email**.
2. Click **Copy** to copy the customer's email address.
3. Forward the email with the order details, in its body or an attachment, to that address.
4. Within a few seconds, the cart shows **Email has been received**. Click **Populate cart from email**.
5. Edit the cart if needed, then check out as normal.

Each customer account has its own address, generated once for all future orders. It takes the form `ai+yourstoreid+has@b2b.sparklayer.io` and can't be changed. 

**Example: a sales agent forwards a customer's email**

A customer emails their sales agent asking for 20 of each of 4 SKUs. The agent signs in as that customer with [Sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md), copies the customer's address and forwards the email. The matching products are added to the cart at a quantity of 20.

## Scan a barcode

Barcodes are synced from your store (see [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md)), so add them to your products in your store admin first.

1. In the cart, click **Scan barcode**. The device needs a built-in camera.
2. Point the camera at a product barcode. If it matches an active product in your store, the product is added to the cart.

To remove **Scan barcode** from the cart, turn it off in the SparkLayer Dashboard.

### Use a barcode scanner

A handheld barcode scanner works on every plan, and suits warehouse or in-store ordering. It types each barcode into the cart's search box, like a keyboard, and the search box accepts both SKUs and barcodes.

1. Set up the scanner to type into the search box at the top of My Cart.
2. Open My Cart and scan. Each scanned product is added to the cart.

The search box needs to be on: see [Choose how customers search](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md#choose-how-customers-search).

## Check quantity rules on added items

Added items follow your inventory and product settings, such as [pack sizes and minimum or maximum quantities](https://docs.sparklayer.io/help/storefront/quantity-rules.md). If a quantity breaks a rule, such as ordering in multiples of 12, the cart shows an import notification, for example: "Your items have been added excluding the following: BRACE-GOLD - Example Bracelet - Quantity rounded to the nearest pack size".

The customer or sales agent can then edit the cart and check out, or submit a quote if you use the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md).

## Hide Intelligent Cart

To remove the Intelligent Cart (AI) features from the cart, turn on **Hide AI features in the cart** at **Settings > Configurations > Pricing and cart** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Pricing and cart** in the Shopify app. It's the same setting as **Hide AI features in the cart** at **Storefront > Options > Checkout** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Checkout** in the Shopify app.

## Data and privacy

SparkLayer never uses uploaded or emailed data for training. It's deleted as soon as the cart is filled, or within 24 hours if it isn't. See [Policies](https://docs.sparklayer.io/help/policies.md).

## FAQs

**Is this using artificial intelligence (AI)?**

Yes. It uses machine learning and related algorithms to scan, interpret and filter files and emails, only to build B2B orders.

**What file types can I upload?**

PDF, XLSX, PNG, JPG, CSV, TXT, JSON and DOCX: documents, spreadsheets and images. See [How it works](#how-it-works).

**Does uploading a file replace what's already in the cart?**

No. The items in the file are added to the cart.

**What if some SKUs are not recognised?**

They're ignored: only SKUs that match your products are added. You can edit the cart by hand afterwards.

**What are typical use cases?**

- Uploading an invoice, purchase order (PO) or other document to reorder items
- Uploading a spreadsheet (XLSX or CSV) of SKUs and quantities
- Taking a photo of a handwritten order, for example at a trade show
- Scanning barcodes in a shop or at an event
- Forwarding any of these, or a customer's email with a product list, by email

**Can customers use this on mobile devices?**

Yes. File upload, barcode scanning and email forwarding all work on mobile.

**Does it work offline?**

No. It needs an internet connection to process files, emails and barcode scans.

**How do I give feedback?**

Email our team at [product@sparklayer.io](mailto:product@sparklayer.io).


---

# Complete draft orders automatically

URL: https://docs.sparklayer.io/help/ordering/automation-and-workflows
Applies to: Shopify

Turn SparkLayer draft orders into completed orders in Shopify automatically, and get email alerts for new draft orders with Shopify Flow.

> **Quick summary**
>
> - On Shopify, B2B orders paid with a manual payment method, such as Pay by Invoice or Pay on Account, arrive as draft orders.
> - To have SparkLayer complete them for you, turn on **Auto-complete draft orders** at **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app.
> - Shopify doesn't notify you about new draft orders, so use [Shopify Flow](https://docs.sparklayer.io/help/platforms/shopify/customisations/flow.md) to send email alerts.
> - These automations are for Shopify only.

## How it works

Unless a customer pays by card at checkout (**Card at checkout** in a customer group), SparkLayer creates a [draft order](https://help.shopify.com/en/manual/online-sales-channels/wholesale/channel/orders/process-orders) in Shopify, under **Orders > Drafts**.

Drafts let you make changes before taking payment and fulfilling, such as adjusting quantities or applying a special shipping method. If you don't need that step, automate it.

What happens to an order paid by invoice or on account:

1. **Customer orders**: They choose a manual payment method, such as Pay by Invoice.
2. **Draft order**: SparkLayer creates a draft order in Shopify.
3. **Auto-complete (optional)**: SparkLayer converts the draft to a completed order.
4. **Fulfil**: You process the order like any other.

## Complete a draft order by hand

To approve a draft order and turn it into a completed order, complete it in Shopify:

1. In the Shopify admin, go to **Orders > Drafts** ([open in the Shopify admin](https://admin.shopify.com/draft_orders)) and open the draft order.
2. Make any changes, such as adjusting quantities or shipping.
3. Click **Mark as paid** if the customer has paid. If they pay later, add payment terms such as Net 30 instead, then create the order.

The completed order is a normal Shopify order, ready to fulfil. See Shopify's guide to [accepting payment](https://help.shopify.com/en/manual/orders/create-orders#accept-payment). If draft orders are piling up, complete them automatically instead.

Draft orders you create yourself in the Shopify admin, rather than through the SparkLayer checkout, don't show in the customer's My Account. To show them, add the `b2b` tag and the order import metafield: see [Show imported or manual orders in My Account](https://docs.sparklayer.io/help/guides/show-imported-orders.md).

## Complete draft orders automatically

1. In SparkLayer, 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.
2. In **Shopify order actions**, turn on **Auto-complete draft orders**.
3. Click **Save**.

The **Shopify order actions** card has 2 switches:

| Setting | What it does |
| --- | --- |
| **Auto-complete draft orders** | Turns draft orders from manual payments into completed orders automatically. |
| **Don't send Shopify's customer invite** | When a sales agent creates a customer in Shopify, Shopify's account invite email isn't sent. See [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#add-a-new-customer). |

## Get email alerts for new draft orders

Shopify doesn't notify you about new draft orders by default. Send an email to an address of your choice, so someone knows to review the order.

[Shopify Flow](https://apps.shopify.com/flow) is a free Shopify app for automating tasks in your store and across apps. For ready-made templates for email notifications and more, see [Shopify Flow for B2B](https://docs.sparklayer.io/help/platforms/shopify/customisations/flow.md).

## FAQs

**Can I use these automations on other platforms?**

No. They're for Shopify, where orders paid with manual payment methods arrive as draft orders.

**Where do I find SparkLayer draft orders in Shopify?**

In the Shopify admin, go to **Orders**, then **Drafts**.

**Why doesn't a draft order I created in Shopify show in My Account?**

My Account only shows orders placed through the SparkLayer checkout. Add the `b2b` tag and set the **B2B - Order Import** metafield to `true` on the order. See [Show imported or manual orders in My Account](https://docs.sparklayer.io/help/guides/show-imported-orders.md).

**Can I mark draft orders as paid automatically?**

**Auto-complete draft orders** turns them into completed orders automatically. To mark an order as paid once the customer pays, open it in Shopify and click **Mark as paid**. See [Complete a draft order by hand](#complete-a-draft-order-by-hand). SparkLayer can't mark orders as paid automatically: to do that, use our [ready-made Shopify Flows](https://docs.sparklayer.io/help/platforms/shopify/customisations/flow.md#order-workflows).


---

# Storefront

URL: https://docs.sparklayer.io/help/storefront

What the SparkLayer frontend adds to your store for signed-in B2B customers, and how to control its design, product display, stock, quantity rules and language.

> **Quick summary**
>
> - When a B2B customer signs in to your store, they see their own prices, a B2B cart and checkout, and an account area. These are SparkLayer's [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) (or widgets), and they sit on top of your existing store theme.
> - Only customers signed in as B2B customers see them. Retail visitors see your store as normal.
> - You add them to your theme at **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app, and control how they behave without code at **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app. Design, product display, stock, quantity rules, text and language can all be changed. Some parts are fixed: see [What you can and can't change](https://docs.sparklayer.io/help/storefront/what-you-can-change.md).
> - The interfaces and customisation are included on every plan.

## How it works

You keep your store, theme and catalogue on your eCommerce platform. SparkLayer adds a script to your store, the [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting), that loads its interfaces. When a B2B customer signs in, the interfaces replace parts of your store with B2B versions, such as product pricing, the cart and the account area.

What a signed-in B2B customer sees:

1. **Customer signs in**: SparkLayer recognises them as a B2B customer and looks up their customer group
2. **Interfaces load**: Product pricing, the B2B cart and My Account replace your theme's own versions
3. **Their rules apply**: Prices, quantity rules, stock display and payment methods come from their customer group
4. **Order placed**: The order is created in your eCommerce platform

The interfaces cover the whole B2B journey: B2B pricing and ordering on product and collection pages, the B2B cart and checkout (**My Cart**), and the customer's account area (**My Account**). You can also add your own content to them with custom slots. See [Storefront widgets](https://docs.sparklayer.io/help/storefront/interfaces.md) for each interface and where it appears.

## Add SparkLayer to your theme

This is your set-up step. **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app offers 3 ways to install the interfaces:

| Option | How it works |
| --- | --- |
| **App embed** (recommended) | SparkLayer's app blocks, turned on in your Shopify theme. No code. Click **Open theme setup**. See [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md). |
| **Ask us to install it** | Our team installs SparkLayer on your theme for you, free. Click **Request installation** and we'll be in touch within a working day. |
| **Manually** | Your developer adds the Core Script to your theme's code. Click **Installation guide**, or see your platform's install guide under [Platforms](https://docs.sparklayer.io/help/platforms.md). |

The same screen has a **Core script version** card. New installs use the latest version. To pin your store to an earlier version, choose it under **Version for this store** and click **Save version**.

**See what's new** lists the changes in each version. The [frontend integration guide](https://docs.sparklayer.io/developers/frontend.md) explains how the Core Script works.

## What you can control

Each of these pages starts with what your customers see, then shows you how to set it up.

- [Storefront widgets](https://docs.sparklayer.io/help/storefront/interfaces.md): Every interface your B2B customers use, and where each appears
- [Storefront options](https://docs.sparklayer.io/help/storefront/storefront-options.md): Change settings, text, checkout fields and My Account sections without code
- [Customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md): Match SparkLayer to your brand colours and fonts, and turn on dark mode
- [What you can and can't change](https://docs.sparklayer.io/help/storefront/what-you-can-change.md): What's a setting, CSS or a slot, what needs a developer and what's fixed
- [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md): Table view, variant modes, SKUs and barcodes, quick buy and 1-click ordering
- [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md): Live stock levels, pre-orders and back-orders, restock dates and reserved stock
- [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md): Pack sizes and minimum or maximum quantities
- [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md): Apply pack sizes, quantity limits and visibility to specific customer groups
- [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md): Change SparkLayer's text, supported languages and locale formats
- [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md): Control which products B2B and retail customers see (free, Shopify only)

## Related features

These features also shape what B2B customers see on your store. They're covered in other sections of the Help Center.

- [How prices are shown](https://docs.sparklayer.io/help/pricing/pricing-display.md): RRP (MSRP) pricing, quantity pricing and unit cost pricing
- [Prices for one customer](https://docs.sparklayer.io/help/pricing/customer-pricing.md): Customer discounts and customer price lists
- [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md): Enable B2B payments, set defaults, rename payment methods and request quotes
- [Cart and checkout](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md): Custom checkout fields, file uploads, terms and conditions and checkout text
- [Shipping and tax](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md): B2B-only shipping, free shipping rules, tax handling and product tax rules
- [Credit and invoicing](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md): Credit limits, account balances, net terms and PDF invoices
- [Customise My Account](https://docs.sparklayer.io/help/customers/account-and-addresses.md): Custom account fields, address editing and display, sales statistics
- [Automation and workflows](https://docs.sparklayer.io/help/ordering/automation-and-workflows.md): Update order statuses and send notifications
- [Order timeline and messages](https://docs.sparklayer.io/help/customers/timeline.md): Track messages and activity across all order types
- [Sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md): Let your team place orders and manage accounts for B2B customers
- [Company users](https://docs.sparklayer.io/help/customers/company-users.md): Let a customer's colleagues share one company account
- [Set up quotes](https://docs.sparklayer.io/help/ordering/quoting.md): Manage the quote-to-order process for your sales team and customers
- [Forms](https://docs.sparklayer.io/help/forms.md): Capture, review and approve wholesale customers from your store


---

# Storefront widgets

URL: https://docs.sparklayer.io/help/storefront/interfaces

See every SparkLayer frontend interface your B2B customers use, from product pricing and the matrix to My Cart and My Account, and where each appears.

> **Quick summary**
>
> - Frontend interfaces (sometimes called widgets) are the B2B parts of your store that SparkLayer adds: product pricing and ordering, the B2B cart and checkout, and the customer's account area.
> - They only appear to customers who are signed in as B2B customers. Retail visitors see your store as normal.
> - You add them to your theme at **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app, with the app embed, a free installation by our team, or by hand. They're loaded by the SparkLayer [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting): keep it up to date to get the latest features.
> - Every plan includes them. On Wix, the product card interface isn't available (see [Wix limitations](https://docs.sparklayer.io/help/platforms/wix/limitations.md)).

## How it works

When a B2B customer signs in, SparkLayer replaces your store's own pricing, "add to cart" buttons, cart and account pages with its interfaces. Each interface uses the customer's [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md) to show their prices, quantity rules, stock and payment methods.

A B2B customer's path through the interfaces:

1. **Browse**: Product card or product price on collection pages
2. **Choose products**: Product detail or product matrix on product pages
3. **Build the order**: My Cart: search, import, edit
4. **Check out**: Shipping, Review & Pay, Complete
5. **Track and reorder**: My Account: orders, lists, addresses

## The interfaces

Each interface page starts with what customers see and do, then shows you how to add and set it up.

| Interface | Where it appears | What customers can do |
| --- | --- | --- |
| [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) | An overlay that opens from your store's cart link, on any page | Build an order, import products, check out and choose a payment method |
| [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) | An overlay that opens from your store's account link, on any page | See order history, reorder, manage shopping lists, addresses and account details |
| [Catalog and Quick Order](https://docs.sparklayer.io/help/sales-ordering/catalog.md) | A tab in the widget, beside My Cart and My Account: **Quick Order** for customers, **Catalog** for sales reps | Browse the range in pictures, search and filter, and add products to the cart in a grid, list or matrix |
| [Product detail](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) | Product pages, in place of the price and "add to cart" area | See their price, stock and pack sizes, and order one or many variants |
| [Product matrix](https://docs.sparklayer.io/help/storefront/interfaces/product-matrix.md) | Product pages, usually for products with two or more variant options | Order every colour and size combination from one table |
| [Product card](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) | Collection (category) pages and anywhere else a product card shows | See their price and add products without opening the product page |
| [Product price](https://docs.sparklayer.io/help/storefront/interfaces/product-price.md) | Anywhere you add it on product or collection pages | See their B2B price or the RRP |

You can also add your own content inside My Cart, My Account and the checkout with [custom slots](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md).

To change how the interfaces look and behave, see [Customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md) and [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md).

- [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md): The B2B cart and four-step checkout.
- [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md): Order history, reordering, shopping lists and addresses.
- [Catalog and Quick Order](https://docs.sparklayer.io/help/sales-ordering/catalog.md): Browse the range in pictures and add to the cart.
- [Product detail](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md): B2B pricing and ordering on product pages.
- [Product matrix](https://docs.sparklayer.io/help/storefront/interfaces/product-matrix.md): Every variant of a product in one table.
- [Product card](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md): B2B pricing and ordering on collection pages.
- [Product price](https://docs.sparklayer.io/help/storefront/interfaces/product-price.md): A B2B price or RRP anywhere on your store.
- [Custom slots](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md): Add your own messages and banners inside My Cart and My Account.


---

# My Cart

URL: https://docs.sparklayer.io/help/storefront/interfaces/my-cart

What B2B customers see and do in the SparkLayer My Cart interface: search, file uploads, shopping lists and discount codes, then a four-step checkout.

> **Quick summary**
>
> - My Cart is SparkLayer's B2B cart and checkout. Signed-in B2B customers see it instead of your store's cart, as a panel over any page.
> - Customers build an order by searching, entering SKUs or barcodes, importing a CSV file or loading a [shopping list](https://docs.sparklayer.io/help/ordering/shopping-lists.md). With [Intelligent Cart](https://docs.sparklayer.io/help/ordering/intelligent-cart.md), they can also upload a PDF or photo, forward an email or scan with their camera. They then check out in four steps: **Cart**, **Details**, **Review & Pay** and **Complete**.
> - You choose the search type at **Settings > Configurations > Pricing and cart** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Pricing and cart** in the Shopify app, and the payment methods each customer sees in their [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md).
> - Some features depend on your plan: Intelligent Cart starts on Starter, file uploads at checkout and B2B discounts on Growth, and the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md) is on Pro and Enterprise (or an add-on on Starter and Growth). See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).

[Try the interactive demo](https://www.figma.com/proto/5FPCY5hSGl7mlwjsjMZI2t/SparkLayer-Interfaces?page-id=0%3A1\&type=design\&node-id=86-36708\&viewport=554%2C-398%2C0.33\&t=34VlPwbCqpvQOTsh-8\&scaling=min-zoom\&starting-point-node-id=35%3A7920\&hide-ui=1) to click through My Cart yourself.

This page is about what your customers see and do in My Cart. The one setting here is [Choose how customers search](#choose-how-customers-search); checkout settings are in [Cart and checkout](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md).

## How it works

My Cart is one of SparkLayer's [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md). When a B2B customer is signed in, it replaces your store's shopping cart with a layout built for B2B ordering. It opens as a panel over the page the customer is on. Tabs at the top let customers switch to the [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) without leaving the page.

From product page to placed order:

1. **Add products**: From product pages, search, a file, an email or a shopping list
2. **Cart**: Review lines, quantities, discounts and the sub-total
3. **Details**: Shipping address and checkout fields, such as a PO number
4. **Review & Pay**: Shipping method, payment method and totals
5. **Complete**: The order is created in your eCommerce platform

In My Cart, customers can:

- Add products by name, SKU or barcode, or from a file or email with Intelligent Cart.
- Change quantities in steps that follow your pack sizes, remove products and clear the cart.
- See how close each line is to its next volume price.
- Save the cart as a shopping list, or load a saved one.
- Enter discount codes, then check out with the payment methods you've allowed for them, such as Pay on Account or Pay by Invoice.
- Pick up a saved cart later, on the same or another device.

### What customers see in My Cart

| Part | What it shows or does |
| --- | --- |
| Tabs | **My Cart** and **My Account**. If Quick Order is on, a **Quick Order** tab follows them: see [Catalog and Quick Order](https://docs.sparklayer.io/help/sales-ordering/catalog.md). |
| Location chip | For [company locations](https://docs.sparklayer.io/help/customers/company-locations.md): the location the customer is ordering for, beside their avatar. |
| Avatar menu | The customer's name and company, then **Expand** and **Log out**. **Expand** widens the panel to give more room to work on the order, and **Minimise** shrinks it again. |
| Step strip | **Cart**, **Details**, **Review & Pay** and **Complete**, with the current step highlighted. |
| Search box | Adds products by name, SKU or barcode, depending on the [search type](#choose-how-customers-search) you choose. The placeholder reads "Add products by name, SKU, or barcode". A handheld barcode scanner can type into it. |
| **Actions** menu | Shortcuts for building and managing the order. See [The Actions menu](#the-actions-menu). |
| Product lines | One row per product. See [Product lines](#product-lines). |
| **Discounts & codes** | Opens a box to enter a coupon code. Applied discounts show as a green label, such as **1 Discount Applied**. See [Discounts and promotions](#discounts-and-promotions). |
| **Sub-total** | The total before tax and shipping, with the number of lines and items. If discounts apply, the price before discounts is shown crossed out. |
| **Checkout** | Starts the checkout. With the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md), **Request Quote** sits beside it for customers who can request quotes (sales agents see **Submit Quote**). See [Quotes](#quotes). |

### The Actions menu

| Item | What it does |
| --- | --- |
| **Upload a file** | Builds a cart from a CSV file (every plan) or, with Intelligent Cart, a spreadsheet, PDF or photo of an order sheet. See [Add products from a file, email or barcode](#add-products-from-a-file-or-email-intelligent-cart). |
| **Forward an email** (Intelligent Cart) | Builds a cart from an order email the customer forwards to their own address. |
| **Scan barcode** (Intelligent Cart) | Adds products by scanning their barcodes with the device's camera. |
| **Clear cart** | Removes every item from the cart, after the customer confirms in a **Clear cart?** box. This can't be undone. |
| **Save shopping list** | Saves the cart as a [shopping list](#save-and-load-shopping-lists). |
| **Shopping lists** | The customer's saved lists: click one to load it. **View all** opens the lists in My Account. |

### Product lines

| Part | What it shows or does |
| --- | --- |
| Image and name | The product photo and name, linking to the product page. |
| SKU and options | The SKU and the variant, for example `SHOE-RED-02 · Red · US 2`. |
| Stock | A coloured dot and the stock status, for example **In stock** with **100+**, or **Pre-order** with its due date (for example **14 Jun 2025**). See [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md). |
| Pack rule | The product's [quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md) in words, for example **Packs of 6** or **Min 12 · Packs of 24**. Hover for the full rule, such as "This product comes in pack sizes of 24, minimum 12". |
| **Customizations active** | Shown when the line has [product customisations](https://docs.sparklayer.io/help/storefront/product-display.md#product-customisations), such as custom text. Hover or tap to see them, for example **Custom Text: ABC 123**. |
| Quantity stepper | **−** and **+** buttons around the quantity. Each click moves one pack, and a typed quantity follows your pack and minimum rules. |
| Line price | The line total, the price per unit, and the RRP crossed out if you show it. |
| **Discounts** | For products with quantity pricing. It says how far the line is from its next volume price, such as **3 more → $9.00/unit** or **2 more packs → $4.75/unit**. Once the line reaches the best price, it reads **Discounts**. Hover to see every quantity break. |
| Delete | The bin icon removes the line. |

## How customers open My Cart

Customers can open My Cart from any page in 3 ways:

| Way in | How it works |
| --- | --- |
| Cart link | Your store's cart (shopping bag) link opens My Cart, as long as it points to `/cart`. |
| Notification | **View order & checkout** in the notification that appears after they add a product. |
| `#spark-cart` link | Any URL ending in `#spark-cart`, for example `https://www.yourstore.com/#spark-cart`. You can use this in your own links and buttons. |

When a customer adds a product, a notification (sometimes called a toast) appears in the top right of the screen. It says **Added to order**, with a **View order & checkout** link. To change its style and animation, see [Customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md). 

## Choose how customers search

The search box at the top of My Cart lets customers add products without browsing your store. You choose one of 2 types:

| Type | What it does | Best for |
| --- | --- | --- |
| **Search** | Searches by product name, product description, SKU, variant name, variant option name and barcode, and shows matching products with a quantity box for each. It handles misspellings and partial matches (a search for `coffe`, `cofee` or `cofe` still finds coffee) and lists the most relevant results first. It also adds exact SKU or barcode matches, like SKU / Barcode Lookup. | Most stores. It gives customers the most features. |
| **SKU / Barcode Lookup** | Adds a product straight to the cart when the customer types an exact SKU or barcode. If there's no exact match, nothing is added. Customers can then edit the quantity. | Customers who only ever order by exact SKU or barcode. |

Search results show the same information as the cart: quantity pricing, pack size rules and stock status. Both types apply your rules as they add a product. For example, [pack sizes](https://docs.sparklayer.io/help/storefront/quantity-rules.md) and minimum or maximum quantities are applied straight away. Barcodes are synced from your store; see [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md).

The search box needs version `3.8` or later of the Core Script, the SparkLayer code in your theme. See [upgrading the Core Script](https://docs.sparklayer.io/developers/frontend.md).

To choose the search type:

1. Go to **Settings > Configurations > Pricing and cart** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Pricing and cart** in the Shopify app.
2. Under **Cart search type**, choose the type you want, or choose **Hide search** to remove the search box.
3. Click **Save**.

### Change the search box text

You can change the placeholder text in the search box. For example, if your products have barcodes, you might tell customers they can search by SKU or barcode.

To do it without code, add a translation override for `cart.quick-order.search-placeholder` at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app.

**For developers: set it in the Core Script**

Add this to your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting):

```javascript title="Core Script"
translations: {
  en: {
    "cart.quick-order.search-placeholder": "Add products by SKU or barcode",
  }
},  
```

For more on changing text, see [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md).

## Add products from a file, email or barcode

The **Actions** menu (or the shortcuts in an empty cart) gives customers quicker ways to fill the cart than searching:

| Customer does | What happens | Plan |
| --- | --- | --- |
| **Upload a file** | Drops in a spreadsheet, PDF or photo of an order sheet. SparkLayer reads the SKUs, barcodes and quantities and adds the matching products to the cart. | Starter and above ([Intelligent Cart](https://docs.sparklayer.io/help/ordering/intelligent-cart.md#build-a-cart-from-a-file)) |
| **Upload a file** with a CSV file, or **Paste rows** | Adds the products from a file with `sku` (or `barcode`) and `qty` columns. | Every plan ([CSV import](https://docs.sparklayer.io/help/ordering/intelligent-cart.md#import-products-from-a-csv-file)) |
| **Forward an email** | Copies their own forwarding address, then forwards an order email to it. | Starter and above ([Intelligent Cart](https://docs.sparklayer.io/help/ordering/intelligent-cart.md#build-a-cart-from-an-email)) |
| **Scan barcode** | Scans product barcodes with the device's camera. | Starter and above ([Intelligent Cart](https://docs.sparklayer.io/help/ordering/intelligent-cart.md#scan-a-barcode)) |
| Scans with a handheld barcode scanner | The scanner types into the search box, and each product is added. | Every plan ([Use a barcode scanner](https://docs.sparklayer.io/help/ordering/intelligent-cart.md#use-a-barcode-scanner)) |

The customer can then edit the cart before they check out. Uploaded files and emails are deleted after 24 hours and never used for training. For file types, column headings and how to rename them, see [Intelligent Cart (AI)](https://docs.sparklayer.io/help/ordering/intelligent-cart.md).

## Save and load shopping lists

Shopping lists let customers save the contents of a cart, so they can reorder the products they buy regularly. See [Shopping lists](https://docs.sparklayer.io/help/ordering/shopping-lists.md).

1. To save the cart, the customer opens **Actions** and chooses **Save shopping list**.
2. They enter a name for the list and click **Save**.
3. To load a list later, they open **Actions** and click the list under **Shopping lists**.

**More detail**

Customers can also save products to a list from any product page. They manage their lists (preview, add to and edit them) in the [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md), which **View all** in the menu opens. Customers and sales agents can export any list as a CSV file to share it across a team.

## Discounts and promotions

Customers enter a coupon code with **Discounts & codes**, under the cart lines or in the **Order Summary** on **Review & Pay**:

1. Click **Discounts & codes**.
2. Enter the code in **Enter a discount code** and click **Apply**.

An order can have up to 3 coupon codes. Discounts can also apply automatically. Applied discounts show as a green label, such as **1 Discount Applied**, with a line naming the discounts the order qualifies for, and the sub-total shows the price before discounts crossed out.

B2B discounts need the Growth plan or above. To set them up, see [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md).

## Check out

When the cart is ready, the customer clicks **Checkout** and works through the 4 steps in the strip at the top of My Cart: **Cart**, **Details** (address and [checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md), such as a PO number or **Upload Files**), **Review & Pay** (shipping method, payment method and totals) and **Complete**. From **Details** onwards, a bar at the bottom of the panel shows the sub-total, a **Back** button and the button for the next step. Customers can also click a finished step in the strip to go back to it.

Each step, and what you can change on it, is in [The checkout, step by step](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md#the-checkout-step-by-step). If the order breaks your [order limits](https://docs.sparklayer.io/help/storefront/quantity-rules.md#order-limit-rules), My Cart shows a message and the customer can't check out until they change it.

### Complete step

The customer sees **Thank you for your order!**, and **View order** opens the order in My Account. The order is sent to your eCommerce platform, and to your backend system if you've connected the [SparkLayer API](https://docs.sparklayer.io/developers/api.md). To change the text, see [Change the order complete message](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md#change-the-order-complete-message); to add your own content, use [custom slots](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md).

## Payment methods

On **Review & Pay**, customers choose from the payment methods their [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md) allows. **Pay Online by Card** takes the customer to your store's checkout to pay straight away. **Pay on Account** and **Pay by Invoice** need no payment details at checkout, and you collect payment later.

For what each method does, their names and order, and how each order arrives in your store, see [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md) and [How orders arrive in your store](https://docs.sparklayer.io/help/ordering/payment-methods.md#how-orders-arrive).

## Quotes

With the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md), customers whose group can request quotes see **Request Quote** next to **Checkout**. They send the cart to your team as a quote instead of placing an order, and can then message your sales team about it until they're ready to complete it. See [Submit a quote instead](https://docs.sparklayer.io/help/ordering/cart-and-checkout.md#submit-a-quote-instead) and [Work on a quote](https://docs.sparklayer.io/help/ordering/work-on-a-quote.md).

## Saved carts

The cart is saved automatically for up to 90 days. If the customer signs out and back in, their products are still there. This also works across devices: a customer can start an order on a desktop computer and finish it the next day on a phone.

## Cart locking

Cart locking stops 2 people changing the same cart at once. This matters most with [sales agent ordering](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md), where a sales agent may be building an order for a customer.

If someone opens a cart that another person is working on, My Cart shows a message at the top, for example **This cart is being edited by a sales agent**. The message includes the time the other person last accessed the cart. They can wait, or click **Take control** to make their own changes and complete the order.

When another sales agent has the same customer open, the cart is locked to that agent, and changes show the warning "You cannot update the cart because it is being processed by a sales agent". Shared sales agent logins make this more likely, so give each person their own. See [Cart locking for sales agents](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#cart-locking).

## Tax

Prices in My Cart are shown excluding tax, unless you show [tax-inclusive prices](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-tax-inclusive-prices), and tax is added on **Review & Pay**. See [Tax and shipping](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md).

## Add your own content

With [custom slots](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md), you can add your own content, such as a message or banner, in set places in My Cart. These include above the products, on each product line, on the **Details** and **Review & Pay** steps, and on the order complete screen.

For other options, see [Storefront](https://docs.sparklayer.io/help/storefront.md).

## FAQs

**How long does SparkLayer keep a customer's cart?**

Up to 90 days. The cart is saved automatically, so it's still there after the customer signs out, and on any device they sign in from.

**Does uploading a file replace what's already in the cart?**

No. The products in the file are added to the cart. See [Intelligent Cart (AI)](https://docs.sparklayer.io/help/ordering/intelligent-cart.md#build-a-cart-from-a-file).

**Why does the quantity jump when a customer clicks + or −?**

The product is sold in packs. Each click moves one pack, and the line's pack rule (for example **Packs of 6**) says so. See [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md).

**Why are my B2B orders arriving as draft orders in Shopify?**

**Shopify only:**

By default, every payment method except **Pay Online by Card** creates a draft order in Shopify. See [How orders arrive in your store](https://docs.sparklayer.io/help/ordering/payment-methods.md#how-orders-arrive).

**Can I link straight to the cart?**

Yes. Add `#spark-cart` to the end of any URL on your store, for example `https://www.yourstore.com/#spark-cart`, and My Cart opens for signed-in B2B customers.


---

# My Account

URL: https://docs.sparklayer.io/help/storefront/interfaces/my-account

Learn what B2B customers can do in the SparkLayer My Account interface: track and export orders, reorder, manage lists and addresses, and hide sections.

> **Quick summary**
>
> - My Account is SparkLayer's B2B account area. Signed-in B2B customers see it instead of your store's account pages, as a panel over any page.
> - Customers can track and export their orders, reorder, manage shopping lists and addresses, see their account and credit details, run purchase reports and manage [company users](https://docs.sparklayer.io/help/customers/company-users.md).
> - You can reorder its sections without code at **Storefront > Options > My Account** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > My Account** in the Shopify app. Order status names and extra account fields are set up in [Customise My Account](https://docs.sparklayer.io/help/customers/account-and-addresses.md).
> - It's included on every plan. Some features it shows depend on your plan, such as [invoices](https://docs.sparklayer.io/help/ordering/invoices.md) and order approval (Growth and above). See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).[Try the interactive demo](https://www.figma.com/proto/5FPCY5hSGl7mlwjsjMZI2t/SparkLayer-Interfaces?page-id=0%3A1\&type=design\&node-id=86-36708\&viewport=554%2C-398%2C0.33\&t=34VlPwbCqpvQOTsh-8\&scaling=min-zoom\&starting-point-node-id=35%3A7920\&hide-ui=1) to click through My Account yourself.This page starts with what your customers see and do in My Account. The settings you control start at [Hide the Financials section](#hide-the-financials-section), [Set up quick links to orders](#set-up-quick-links-to-orders) and [Reorder or hide sections](#reorder-or-hide-sections).## How it worksMy Account is one of SparkLayer's [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md). When SparkLayer is installed, it replaces your store's own account area for B2B customers. It opens as a panel over the page the customer is on, with a greeting that uses the customer's first name, such as "Welcome back".

**My Cart** and **My Account** tabs at the top let customers switch to the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) without leaving the page.In My Account, customers can:* See every order they've placed, with its payment status and status, and filter, search and export them.
* Reorder a whole order, a single product or everything bought in a time period.
* Load, edit and delete their shopping lists.
* Add, edit and delete addresses, and choose their default addresses.
* See their account details and, if you use them, their credit limit, balance and payment terms.
* Message your team about orders and quotes, and manage company users if you've turned that on.How customers reorder from My Account:

1. **Recent Activity**: Open a past order, report or shopping list
2. **Actions**: Add the items to the current cart, or start a new cart with them
3. **My Cart**: Adjust quantities and check out### SectionsMy Account is made up of these sections, shown in this order by default. You can [reorder or hide them](#reorder-or-hide-sections).| Section             | What customers see and do                                                                                            | Name in code (for developers) |
| --- | --- | --- |
| Custom content | Your own content at the top of the page, if you've added a [custom slot](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md) | `spark-slot-my-account` |
| **Recent Activity** | Their latest orders and quotes, with a **Status** filter and **View all** for the full list | `recent-activity` |
| **Favourites** | The products they've saved with the heart icon, if [favourites](https://docs.sparklayer.io/help/ordering/favourites.md) are on, with **View all** | – |
| **Shopping Lists** | Their saved shopping lists, each with an **Actions** menu to load or delete it | `shopping-lists` |
| **Financials** | Their **Payment terms**, **Unpaid Balance** and **Credit Limit**, if you use credit terms | `financials` |
| **My Details** | Their email address and name, plus any custom fields | `my-details` |
| **Reports** | Their purchase history by time period | `reports` |
| **Address Book** | Their saved addresses, with **Add new address** | `address-book` |
| **Company Users** | The people who share the account, with **Invite new user**, if [company users](https://docs.sparklayer.io/help/customers/company-users.md) is on | `company-users` |With [company locations](https://docs.sparklayer.io/help/customers/company-locations.md), several sections follow the location the customer is ordering for: see [Company locations in My Account](#company-locations-in-my-account).## How customers open My AccountCustomers can open My Account from any page in 2 ways:| Way in | How it works |
| --- | --- |
| Account link | Your store's account link, usually in the header, opens My Account, as long as it points to `/account`. |
| `#spark-account` link | Any URL ending in `#spark-account`, for example `https://www.yourstore.com/#spark-account`. |When a signed-in customer goes to your store's own account pages (for example `/account`), they're redirected to My Account. To send B2B customers to a different URL after they sign in, your developer can update the Core Script. See [Customise My Account](https://docs.sparklayer.io/help/customers/account-and-addresses.md).## Order historyEvery order a customer places through SparkLayer is saved to their order history. The **Recent Activity** section lists them, newest first:| Column | What it shows |
| --- | --- |
| **Reference** | The order or quote reference. Click it to open the order. |
| **Submitted on** | The date the order was placed. |
| **Payment** | The payment status, such as **Pending** or **Paid**. |
| **Status** | The order status, such as **Processing** or **Shipped**. See [Order statuses](#order-statuses). |
| **Amount** | The order total. |The **Status** menu at the top of the section filters the list, for example to **All**, **Processing** or **Shipped**. Each option shows a count. Other filters, such as **Awaiting merchant** or **Requires approval** (for [company users](https://docs.sparklayer.io/help/customers/company-users.md)), appear when the customer has orders in them. Customers click an order's reference to see its full details, however it was paid for. To rename the order statuses customers see, see [Customise My Account](https://docs.sparklayer.io/help/customers/account-and-addresses.md).### Search and filter ordersTo see all their orders, customers click **View all** in **Recent Activity**. This opens the Activity view, where they can filter and search:| Filter | Options |
| --- | --- |
| Date | Choose a year or a time period (within a 365-day period), or **Custom Date Range** with a **Start Date** and **End Date**. |
| Search | Search by order ID, purchase order (PO) number, or address (first line, second line, city or zip code). |### Order detailsBy default, My Account shows completed orders, and purchases that exist only in SparkLayer, such as quotes and orders waiting for approval. Draft orders in your store aren't listed.An order opens on its own page, headed with its reference (for example **My Account › #1001**), with 3 tabs and an **Actions** menu for [reordering](#reorder).| Tab | What it shows |
| --- | --- |
| **Summary** | The **Order Summary**: **Payment Status**, **Status**, **Payment Method**, **Shipping Method**, **Submitted on**, any **Additional Information** (such as a preferred shipping date) and the **Shipping Address**. **View & download invoice** opens the invoice, where there is one. |
| **Order Lines** | Every product ordered, grouped by status, with its quantity, SKU and options, line total, quantity × unit price and RRP. Each line has **Order again**. Under the lines, the **Order Total**: **Sub-total**, **Shipping**, **Tax**, **Total**, **Paid** and the **Balance**, with its due date and terms for orders paid on account. |
| **Timeline**    | Messages and events for the order. See [Timeline and messages](#timeline-and-messages).                                                                                                                                                                                                                                              |**More detail**

- **Status** is based on the status sent from your store admin or backend system, for example Processing, Shipped or Cancelled.
- **Payment Status** is, for example, Pending or Paid, and **Payment Method** shows how the order was paid for, for example On Account. See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md).
- On Shopify, you can [customise the order number](https://docs.sparklayer.io/help/platforms/shopify/metafields.md).
- Where you've supplied a tracking number, it shows on the order too. See [Customise My Account](https://docs.sparklayer.io/help/customers/account-and-addresses.md).### Order statusesAn order's status sums up the status of all the packages in it. For example, if half the items have shipped and half are still processing, the order shows as **Part-shipped**. Customers can open the order to see the status of each package.| Order status      | Shown when the packages are                   |
| --- | --- |
| **Processing** | `Processing`, or `Processing` and `Cancelled` |
| **Shipped** | `Shipped` |
| **Cancelled** | `Cancelled` |
| **Returned** | `Returned` |
| **Part-returned** | `Returned` and `Processing` |
| **Part-shipped** | `Shipped` and `Processing` |
| **Varied** | Any other mix |SparkLayer also has its own statuses, which don't match a status in your eCommerce platform:| Status | What it means |
| --- | --- |
| **Awaiting Approval** | A [limited user](https://docs.sparklayer.io/help/glossary.md#limited-user) has submitted an order, and the main company user needs to approve it. |
| **Awaiting merchant** | The customer has placed the order, but it isn't a completed order in your store yet: usually a Pay on Account or Pay by Invoice order that's still a draft order for you to complete. It has a purchase ID, such as `P#1264`. You see it as **Awaiting merchant** in **Orders** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/activity)), or **SparkLayer Wholesale > Orders** in the Shopify app too. See [Awaiting merchant](https://docs.sparklayer.io/help/glossary.md#awaiting-merchant). |
| **Archived**          | The order has been archived. For example, if a user cancels an order before it's approved, it's archived.                                                                                                                                                                                                                                                                                                                                                                         |Orders paid on account or by invoice arrive in your store as draft orders, so they show as **Awaiting merchant** until you complete them, and their **Payment** shows **Pending** until they're paid. On Shopify, **Auto-complete draft orders** at **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app turns them into completed orders automatically.Purchases that exist only in SparkLayer, such as orders waiting for approval and quotes, have an internal ID. By default it starts with `P#`, for example `P#1264`. You can change this prefix, and add a suffix, with **Purchase ID prefix** and **Purchase ID postfix** at **Settings > Configurations > Store** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Store** in the Shopify app.### Offline and archived ordersYou can show orders placed outside SparkLayer, for example over the phone, so customers see their whole order history in one place. Send them with the [SparkLayer API](https://docs.sparklayer.io/developers/api.md). On Shopify, you can also show orders you created in the Shopify admin or imported, with the `b2b` tag and an order metafield: see [Show imported or manual orders in My Account](https://docs.sparklayer.io/help/guides/show-imported-orders.md).### InvoicesDepending on your setup, customers can view and download invoices from their order history, with **View & download invoice** on the order's **Summary**. See [Credit limits and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md).### Export ordersCustomers can download their orders as a CSV file, for example to reconcile them with their own systems or analyse what they buy. The customer:1) Clicks **View all** in **Recent Activity**.
2) Searches or filters the list to export only some orders. The export includes only the orders shown. For example, filtering by **Quote** exports only quotes.
3) Opens the **Download** menu in the top right and chooses an option:| Option                       | What the file contains                                                                                                                |
| --- | --- |
| **Activity** | One row per order, with order details such as the order number, date, status and total. Best for an overview. |
| **Activity with line items** | One row per product line, with product details, quantities, prices, shipping and tracking. Best for analysing products across orders. |If you use custom fields or line item attributes, they're added as extra columns in the **Activity with line items** export. Custom field columns start with `custom_`.## ReorderCustomers can repeat a past order, or order individual products again.| To reorder | How |
| --- | --- |
| A whole order | On the order's page, open **Actions** in the top right and choose an option (see below). |
| One product | Click **Order again** next to the product in the order's **Order Lines**. |
| Everything bought in a time period | Use [Reports](#reports). |The **Actions** menu has 2 options:| Option | What it does |
| --- | --- |
| **Add items to existing cart** | **Adds** the products from the order to what's already in the cart. |
| **Create new cart** | **Replaces** what's in the cart with the products from the order. |Products that aren't available (for example, out of stock) aren't added, unless you've allowed customers to order unavailable products.## Shopping listsShopping lists let customers reorder products they've saved, such as a range they always buy or a list of favourites. Every list saved from the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) appears in the **Shopping Lists** section. See [Shopping lists](https://docs.sparklayer.io/help/ordering/shopping-lists.md).| Item | Details |
| --- | --- |
| **Name** | The name the customer gave the list when saving it in My Cart. |
| **Last Updated** | When the list was last changed (usually when it was created). |
| **Actions** | **Add items to existing cart** adds the list's products to what's already in the cart. **Create new cart** empties the cart and adds the list's products. **Delete** deletes the list. |## ReportsThe **Reports** section shows customers what they've bought. They can filter by time period and reorder straight from a report.| Report | Details |
| --- | --- |
| **Purchase history by time period** | Every product the customer has bought over a period, such as by quarter, month or week. They can reorder a whole range of products in a few clicks and go straight to checkout. |Reports have these limits:| Limit | Details |
| --- | --- |
| Time periods | Only the **4 most recent periods** of the selected time range are shown. |
| Products | Up to 100 products are shown for a time period. |## Address bookCustomers see their saved addresses in My Account, and can choose any of them at checkout in the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md). The addresses come from your store admin, or from your backend system through the [SparkLayer API](https://docs.sparklayer.io/developers/api.md).| Item | Details |
| --- | --- |
| **Default shipping address** | The address used for shipping by default, marked with a label. |
| **Default billing address** | The address used for billing by default, marked with a label. |
| Other addresses | Every other saved address. |Customers can manage their own address book:| Task | How |
| --- | --- |
| Add an address | Click **Add new address**. |
| Edit an address | Open **Actions** next to it and choose **Edit address**. |
| Delete an address | Open **Actions** next to it and choose **Delete address**. A default address can't be deleted. |Address management is on by default. To turn it off, or to stop customers changing their default billing address, see [Allow address editing](https://docs.sparklayer.io/help/customers/account-and-addresses.md#allow-address-editing).### Address autocompleteWhen customers add or edit an address, they can start typing and choose a suggested address to fill in the rest of the form. This saves typing and reduces mistakes, so orders reach the right place first time.Suggestions favour your store's country, but matches further afield still appear, so international customers can find their address too.### Local address formatsThe address form adapts to the country the customer chooses:| What changes | Example |
| --- | --- |
| **Field order and labels** | The first name and last name fields swap places where that's the local convention. |
| **Local terms**            | Customers in Japan see "Prefecture" instead of "Region".                           |These labels are translated into every language SparkLayer supports.## Account detailsThe **My Details** section shows the customer's **Email address** and **Name**.If you use [credit terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md), the **Financials** section shows their **Payment terms**, **Unpaid Balance** and **Credit Limit**. A note tells them that payments may take some time to update. This information comes from the customer's record in your store admin, or from your backend system through the [SparkLayer API](https://docs.sparklayer.io/developers/api.md).You can also add your own fields to **My Details**, such as a website address or sales agent contact details. See [Customise My Account](https://docs.sparklayer.io/help/customers/account-and-addresses.md).### Hide the Financials sectionTo stop customers seeing **Financials** while you still use credit terms, hide it. You don't need code:1) Go to **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app and open **My Account**.
2) Turn on **Hide financial figures**. This hides financial figures everywhere, and the Financials section too.
3) Click **Save and publish**.**Core Script code for your developer**

Your developer can do the same in the `display` section of your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting) instead:

```javascript title="Core Script"
display: {
  hideFinancials: true,
},
```## Company users[Company users](https://docs.sparklayer.io/help/customers/company-users.md) lets a business share one account across a team, with permissions for what each person can do. It's sometimes called company roles or sub-accounts.When it's on, the **Company Users** section appears in My Account, listing each person's **Name**, **Email** and **Role**. The main user can add people with **Invite new user**, and remove them with **Actions** > **Delete user**.## Company locations in My Account**Shopify only:**

On Shopify, a B2B company can have several [locations](https://docs.sparklayer.io/help/customers/company-locations.md), such as stores or branches. The customer orders for one location at a time, and My Account follows it:

| Section | What changes |
| --- | --- |
| **Recent Activity** | Shows the location's orders (and, for a region, its stores' orders), each naming the location it was placed for. A location with no orders says so, with **Change location**. |
| **Financials** | The location's unpaid balance, with the company's credit limit, which every location shares, and how much of it is left. |
| **My Details** | The signed-in person's own name and email address, not the company's. |
| **Address Book** | The location's address, as the default shipping and billing address, with **Change location**. |
| **Company Users** | Each person's locations, and **(you)** beside the signed-in person. |## Timeline and messagesThe [Timeline](https://docs.sparklayer.io/help/customers/timeline.md) shows the messages, notes, events and related email notifications for an order or [quote](https://docs.sparklayer.io/help/ordering/quoting.md). Customers see it on the order's **Timeline** tab. When your team notifies a customer, they get an email and sign in to their account to reply.## Set up quick links to ordersSparkLayer can take a customer or sales agent straight to an order or quote when they click a link. This helps in these cases:| Scenario | Example |
| --- | --- |
| [Company users](https://docs.sparklayer.io/help/customers/company-users.md) | A main user opens an order to approve from an email about a limited user's order. |
| [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md) | A customer or sales agent opens a quote from an email. |
| [Orders](https://docs.sparklayer.io/help/dashboard/orders.md)               | You open an order from **Orders** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/activity)), or **SparkLayer Wholesale > Orders** in the Shopify app in SparkLayer. |To turn this on, add a one-line script to your store's code. It must load for every visitor, signed in or not.If a customer or sales agent is already signed in, they're taken to the order whether or not the script is added.**Shopify:**

1. In your Shopify admin, go to **Online Store > Themes** ([open in the Shopify admin](https://admin.shopify.com/themes)).
2. Edit the code of your live theme and open `theme.liquid`.
3. Add this line just before the closing `</head>` tag, then save:

   ```html title="theme.liquid"
   <script async src="https://cdn.sparklayer.io/spark-redirect.js"></script>
   ```

**Other platforms:**

Add this line to your website's code, just before the closing `</head>` tag:

```html
<script async src="https://cdn.sparklayer.io/spark-redirect.js"></script>
```## Reorder or hide sectionsYou can change the order of the sections in My Account, for example to move **Address Book** higher up. You don't need code.1) Go to **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app and open **My Account**.
2) Under **Account sections, in order**, drag the sections into the order you want. Each one shows whether it's **Visible**.
3) Click **Save and publish**.See [Storefront options](https://docs.sparklayer.io/help/storefront/storefront-options.md#my-account-sections).### For developers: reorder or hide sections in the Core ScriptYour developer can set the order and hidden sections in the `display` section of your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting) instead. They use the names in code from the [Sections](#sections) table: list the sections in `order`, and add any to hide to `hide`.**Core Script code for your developer**

To set the order, list the sections in the order you want:

```javascript title="Core Script"
display: {
  sectionConfiguration: {
    'my-account': {
      order: [
        'recent-activity',
        'shopping-lists',
        'financials',
        'my-details',
        'reports',
        'address-book',
        'company-users',
      ],
      hide: [],
    },
  },
},
```

To hide sections, add them to `hide`. This example hides the reports, address book and company users sections:

```javascript title="Core Script"
display: {
  sectionConfiguration: {
    'my-account': {
      order: [
        'recent-activity',
        'shopping-lists',
        'my-details',
        'reports',
        'address-book',
        'company-users',
      ],
      hide: [
        'reports',
        'address-book',
        'company-users',
      ],
    },
  },
},
```### Hide sections for some customersYou can show different sections to different customers, for example to hide **Recent Activity** from limited users. This needs a developer: they build the `order` or `hide` list in your platform's template code.**Shopify:**

Use Liquid to hide sections based on the customer's [company user](https://docs.sparklayer.io/help/customers/company-users.md) role. This example hides **Recent Activity** from limited users:

```javascript title="Core Script"
display: {
  sectionConfiguration: {
    'my-account': {
      hide: [
        {% if customer.metafields.sparklayer.role == 'limited-customer' %}
          'recent-activity',
        {% endif %}
      ],
    },
  },
},
```

The same approach works with customer tags:

```javascript title="Core Script"
display: {
  sectionConfiguration: {
    'my-account': {
      hide: [
        {% if customer.tags contains 'b2b-vip' %}
          'recent-activity', // Hide recent activity if the customer is b2b-vip
        {% endif %}
      ],
    },
  },
},
```

**Other platforms:**

Use your platform's own template logic to output the `hide` (or `order`) list for each customer, in the same format as the examples above.## Add your own contentWith [custom slots](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md), you can add your own content at the top of My Account. For example, a welcome message or a promotion customers see as soon as they sign in.To add it, go to **Storefront > Options > Custom slots** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Custom slots** in the Shopify app and add the `spark-slot-my-account` slot. It then appears as a **Custom Slot** section in the account sections list, where you can drag it into place. If you set the section order in the Core Script, your developer adds `spark-slot-my-account` to the `order` list above to choose where it sits.For other options, see [Storefront](https://docs.sparklayer.io/help/storefront.md).## FAQs**Why can't a customer see an order in My Account?**

By default, My Account lists completed orders and purchases that exist only in SparkLayer, such as quotes. Draft orders in your store aren't shown. Orders placed outside SparkLayer, such as phone orders, only appear if you send them with the [SparkLayer API](https://docs.sparklayer.io/developers/api.md). On Shopify, orders you created in the admin or imported show once they have the `b2b` tag and the order import metafield: see [Show imported or manual orders in My Account](https://docs.sparklayer.io/help/guides/show-imported-orders.md).

**Why weren't all the products added when a customer reordered?**

Products that aren't available, for example because they're out of stock, aren't added unless you've allowed customers to order unavailable products.

**Can I link straight to My Account?**

Yes. Add `#spark-account` to the end of any URL on your store, for example `https://www.yourstore.com/#spark-account`.


---

# Product detail

URL: https://docs.sparklayer.io/help/storefront/interfaces/product-detail

Add the SparkLayer product detail interface to product pages so B2B customers see their price, stock and pack sizes and order one or many variants.

> **Quick summary**
>
> - The product detail interface replaces the price and "add to cart" area on your product pages for signed-in B2B customers. Retail visitors see your page as normal.
> - It shows the customer's own price (including quantity pricing), the RRP, SKU, stock and quantity rules, and lists every variant in a table so customers can order several at once.
> - On Shopify it's added automatically on supported themes, or as the **SparkLayer - Product Page** app block. On other platforms, you add one line of code to your product page template. On Wix, it's added to product pages automatically.
> - It's included on every plan. Our team can install it for you free of charge.

## How it works

The product detail interface is one of SparkLayer's [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md). When a signed-in B2B customer opens a product page, it takes the place of your theme's price and "add to cart" area.

It adapts to the product. A simple product gets a single quantity box, and a product with variants (for example colour and size) gets a table of variants.

With the product detail interface, customers can:

- See their own price, any quantity pricing, and the RRP if you show it.
- See the SKU (product code), barcode and stock availability, including pre-orders.
- Choose a quantity that follows your [quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md), such as pack sizes.
- Order several variants at once and add them to their cart with one click.

To see what customers see, explore the product interfaces in [our interactive demo](https://www.figma.com/proto/5FPCY5hSGl7mlwjsjMZI2t/SparkLayer-Interfaces?page-id=0%3A1\&type=design\&node-id=86-36708\&viewport=554%2C-398%2C0.33\&t=34VlPwbCqpvQOTsh-8\&scaling=min-zoom\&starting-point-node-id=35%3A7920\&hide-ui=1).

Ordering from a product page:

1. **Check the price**: "From" shows the best price; each row shows the price at its quantity
2. **Set quantities**: Steppers move a pack at a time; **Qty rules apply** lists the rules
3. **Add to Cart**: Adds every line with a quantity and opens My Cart

### Products with variants

For a product with variants, such as styles or colours, customers see the variants in a table, so they can order several at once:

| Part | What it shows or does |
| --- | --- |
| Price | **From:** the lowest price any quantity break reaches, then the RRP (for example "From: $4.75 MSRP: $9.99"). **Qty discount pricing available** appears under it when the product has quantity pricing. |
| Variant options | A table row for each variant, under a column named for the option (for example **Style**). For products with a second option, a list to choose it (for example **Size**). |
| Variant details | Each variant's thumbnail (a larger copy appears on hover), name, SKU and barcode (**Code**). |
| **Price** column | The variant's price at the row's quantity, its RRP, its pack price (for example "Pack (6): $40.50") and its volume deal: see [Volume pricing](#volume-pricing). |
| **Stock** column | A coloured dot and the stock count, such as **100+**. Hover over the dot for the status, such as **In stock**. |
| **Qty** column | A stepper for each variant (**−**, the quantity, **+**) that moves one pack at a time, with **Qty rules apply** under it when rules are set. See [Quantity rules](#quantity-rules). |
| Stock key | Under the table: **In stock**, **Low stock**, **Last stock**, **Out of stock** and **Pre-order**, each in its own colour. |
| **Add to Cart** | Adds every variant with a quantity to the order, and shows the total. See [Add to Cart](#add-to-cart). |
| Shopping list and heart | Save the product to a [shopping list](https://docs.sparklayer.io/help/ordering/shopping-lists.md) or to [favourites](https://docs.sparklayer.io/help/ordering/favourites.md). |

A variant with no stock shows as **Out of stock** and can't be ordered, unless you've allowed customers to buy out-of-stock products.

For products with two or more option types and many options, the [product matrix interface](https://docs.sparklayer.io/help/storefront/interfaces/product-matrix.md) shows every combination in one grid.

### Products without variants

For a product with a single option to buy, customers see these parts:

| Part | What it shows or does |
| --- | --- |
| Price | **From:** the lowest price any quantity break reaches, then the RRP if set (for example "From: $6.99 MSRP: $14.99"). |
| Product code | **Product Code** with the SKU, and **Code** with the barcode if the product has one. |
| Stock | Stock availability, for example **In stock** with how many are available, or **Pre-order** with its due date or a note such as "Awaiting date from supplier". |
| Quantity pricing table | If the product has quantity pricing, each break with its **Qty**, **Price** and **Savings**. For a product sold by unit of measure, each row names the unit, for example "1 (single)", "5 (case)" and "10 (pallet)". |
| Quantity | A stepper beside **Add to Cart**, opening at one unit, that applies your quantity rules. **Qty rules apply** appears under it when rules are set. |
| **Add to Cart** | Adds the product to the order. The button shows the total for the chosen quantity, for example **Add to Cart ($10.00)**. |

### Volume pricing

Each variant row says, in words, what its quantity pricing is worth. The text is underlined with dots because customers can click it. It opens the variant's **Qty discount pricing** table, with each break's **Qty**, **Price** and **Savings**. Clicking a row of that table sets the quantity to that break, in whole packs.

| The row says | When |
| --- | --- |
| "From $4.75 at 2+ packs" | The best price needs more than one pack. Breaks are rounded up to whole packs and counted in packs. |
| "$4.75 each by the pack" | One pack already reaches the best price. |
| "From $4.75 for 10+" | The product has no pack size. |
| "Saving 15%" | The row's quantity has reached a break. Savings are whole percentages, rounded. |

On a product sold by unit of measure, the break is stated per unit, for example "From $3.99 per unit".

### Quantity rules

The interface applies your quantity rules as customers choose quantities. A pack size is set per variant. A minimum or maximum is set per product and counted across all its variants: for example, a minimum of 36 can be met with 12 of each of 3 styles. See [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md).

- **Qty rules apply** under each stepper opens a **Quantity rules** box: the **Pack size** ("Orders go in multiples of 6"), the **Minimum** and **Maximum** across all variants, and where the customer stands, for example "6 chosen · add 30 more".
- The label turns amber while the minimum isn't met.
- A typed quantity is rounded up to whole packs: 7 of a pack of 6 becomes 12.
- At the maximum, **+** stops and a typed quantity is capped.

### Add to Cart

**Add to Cart** is greyed out until the customer chooses a quantity, and while the quantity rules aren't met. Hovering over it tells the customer why, for example "Please select a quantity" or "Add 30 more to reach the minimum of 36".

Once the rules are met, the button shows the total, for example **Add to Cart ($34.50)**. Clicking it adds every chosen line to the cart and opens [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md). To change the button text, see [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md#change-the-add-to-cart-button-text).

## Add the interface to your store

This section is for you, the merchant. To have our team install the product detail interface for you, free of charge, click **Request installation** at **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app. Or add it yourself:

**Shopify:**

There are 2 ways to add the product detail interface on Shopify:

1. **Theme setup:** go to **Home > Setup > Theme setup** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Setup > Theme setup** in the Shopify app. Under **Optional blocks**, click **Add** next to **Product block**. Shopify's theme editor opens at that block: put it where you want the interface to appear, and save. See [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md).

   **More detail**

   In the theme editor, the block is called **SparkLayer - Product Page**. You can also add it yourself: go to **Online Store > Themes** ([open in the Shopify admin](https://admin.shopify.com/themes)), click **Customize**, open a product page and add the block.

2. **Code (for your developer):** if your theme doesn't support app blocks, or you'd rather use code, add this line to your product page template:

   ```html
   <spark-pdp parent-id="{{ product.id }}"></spark-pdp>
   ```

**Other platforms:**

Your developer adds this line to your product page template:

```html
<spark-pdp parent-id="{{ product.id }}"></spark-pdp>
```

Replace `product.id` with the variable your platform uses for the product's ID. See the install guide for your platform under [Platforms](https://docs.sparklayer.io/help/platforms.md).

On Wix, the interface is added to your product pages automatically when you install SparkLayer.

Once it's added, every signed-in B2B customer sees the interface on your product pages and can start ordering.

## Change what it shows

You can change many parts of the interface, such as showing all variants at once, and showing the RRP, stock and barcodes. See [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md).

## FAQs

**Why does a variant show as unavailable?**

A variant with no stock shows as unavailable, unless your setup allows customers to buy out-of-stock products. See [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md).

**Do retail customers see the product detail interface?**

No. It only appears for customers signed in as B2B customers. Everyone else sees your theme's normal product page.


---

# Product matrix

URL: https://docs.sparklayer.io/help/storefront/interfaces/product-matrix

Use the SparkLayer product matrix to show every colour and size of a product in one table so B2B customers can order in bulk, and apply it with tags.

> **Quick summary**
>
> - The product matrix interface shows every variant of a product in one table (a matrix), for example colours down the side and sizes across the top, so B2B customers can order many combinations at once.
> - Use it for products with 2 or more variant option types and many options. For other products, the [product detail interface](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) works better.
> - You (or your developer) add it to your product page template with one line of code. On Shopify, you can use a product tag to show it only on some products.
> - It's included on every plan.

## How it works

The product matrix interface is one of SparkLayer's [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md). It replaces parts of your product page with a table that shows every variant of the product in a single view.

Each cell is one combination, for example a cream sweatshirt in small, with its price, stock and a quantity box. Customers fill in the quantities they want and click **Add to Cart** once.

You can see it working on our [example product page](https://demo.sparklayer.io/collections/b2b-grid-mode/products/example-running-shoes).

With the product matrix, customers can:

- See every combination of a product's options at once.
- Enter quantities for many variants and add them all to the order in one go.
- See which variants are in stock, low on stock or out of stock before they order.

Each part of the matrix shows customers something different:

| Part | What it shows |
| --- | --- |
| **Product pricing** | The customer's B2B price and, if you show it, the RRP. |
| **Variants** | A matrix of every available variant. The first option (for example **Colour**) runs down the side with an image of each, and the second (for example sizes) runs across the top. |
| **Stock level** | A coloured dot in each cell showing the variant's stock status, for example in stock, low stock, out of stock or pre-order. Out-of-stock cells can't be ordered. |
| **Quantity** | A quantity box in each cell that applies your [quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md). |
| **Quantity pricing** | Any quantity pricing, shown in an information pop-up on each cell. |
| **SKU** | The product code, shown in the same information pop-up. |
| **Add to Cart** | Adds every variant with a quantity to the order, and shows the total. |

### Products with more than two option types

If a product has more than 2 option types, the extra options appear inside the table as an extra row of column headings. For example, a T-shirt with **Colour**, **Size** and a logo option shows each size (Small, Medium, Large) split into **With Logo** and **No Logo** columns, with a row for each colour.

## Add the interface to your store

This section is for you and your developer. Adding the product matrix means a small change to your theme's code, so your developer or agency usually does it. They add this line to your product page template:

```html
<spark-product-matrix parent-id="{{ product.id }}"></spark-product-matrix>
```

If your platform uses a different variable for the product's ID, replace `product.id` with it. See the install guide for your platform under [Platforms](https://docs.sparklayer.io/help/platforms.md). Once it's added, every signed-in B2B customer sees the matrix on that page and can start ordering.

The matrix needs room. Place it where customers can see the whole table, for example below the product image and description, set to the full width of the page.

### Show the matrix on some products only (Shopify)

**Shopify only:**

To use the matrix only for certain products, tag those products. Your developer then chooses the interface in your theme code:

1. In your Shopify admin, add a tag such as `b2b-product-matrix` to each product that should use the matrix.
2. Go to **Online Store > Themes** ([open in the Shopify admin](https://admin.shopify.com/themes)) and edit the code of your theme.
3. Open your product page section, for example `sections/main-product.liquid`, and add this Liquid code where the interface should appear. Tagged products then show the matrix, and all other products show the [product detail interface](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md).

```html
<!-- Show Product Matrix Interface for tagged products -->

{% if product.tags contains 'b2b-product-matrix' %}
     <spark-product-matrix parent-id="{{ product.id }}"></spark-product-matrix>
{% else %}
    <!-- Don't show anything -->
{% endif %}

 <!-- Show regular Product Detail Interface for other products-->

{% if product.tags contains 'b2b-product-matrix' %}
    <!-- Don't show anything -->
{% else %}
    <spark-pdp parent-id="{{ product.id }}"></spark-pdp>
{% endif %}
```

On other platforms, use your platform's own way of adding custom code to product templates.

## Change what it shows

To show restock dates in the matrix, or for the display options that apply to all the product interfaces, see [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md#show-variants-as-a-matrix-matrix-mode).

## FAQs

**Should I use the product matrix or the product detail interface?**

Use the product matrix for products with 2 or more variant option types (such as colour and size) and a large number of options. For simpler products, use the [product detail interface](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md).

**Where can customers see quantity pricing and the SKU in the matrix?**

Both are in the information pop-up on each cell of the table.


---

# Product card

URL: https://docs.sparklayer.io/help/storefront/interfaces/product-card
Applies to: Shopify, BigCommerce, WooCommerce, Magento

Add the SparkLayer product card interface to collection pages so B2B customers see their price, variants and stock and order without opening a product.

> **Quick summary**
>
> - With the product card interface, signed-in B2B customers see their own price, choose a variant and quantity, and add products to their order without opening the product page.
> - It replaces the price and "add to cart" area on your product cards: the product tiles on collection (category) pages, product recommendations and anywhere else your store lists products.
> - On Shopify it's added automatically on supported themes, or as the **SparkLayer - Product Card** app block. On other platforms, you add one line of code to your product card template.
> - It's included on every plan. It isn't available on Wix, where product prices on gallery pages are hidden instead (see [Wix limitations](https://docs.sparklayer.io/help/platforms/wix/limitations.md)).

## How it works

The product card interface is one of SparkLayer's [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md). It takes the place of the price and "add to cart" button on each product card. B2B customers can then see their pricing and start building an order while they browse.

With the product card, customers can:

- See their B2B price and, if you show it, the RRP.
- See the best volume price and open the product's quantity pricing.
- Choose a variant from a drop-down list (one list per option, such as colour and size).
- Choose a quantity that follows your quantity rules, and add the product to their order.

Your theme's card still shows the product photo, title and any tags above it. The interface adds these parts, top to bottom:

| Part | What it shows or does |
| --- | --- |
| **Price** | The customer's B2B price, with **From:** when the price depends on the variant or quantity, and, optionally, the RRP (for example "From: $4.99 MSRP: $9.99"). |
| **Volume break** | The best quantity price, for example "From $8.30 at 8+ packs" or "From $3.99 per unit", underlined with dots. Clicking it opens the quantity pricing table (**Qty**, **Price** and **Savings**) as wide as the card. Clicking a row sets the quantity to that break. Breaks are rounded up to whole packs and counted in packs. |
| **Stock and pack size** | One line with the stock status (for example **In stock** · **100+**, or **Pre-order** with a due date) and the pack rule, such as **Packs of 6**. |
| **Variants** | A drop-down list for each option, such as colour and size. |
| **Quantity** | A stepper that applies your [quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md), opening at the pack size. Each click moves one pack. |
| **Add** | Adds the product to the order and opens My Cart. The button shows the total for the chosen quantity, for example **Add $71.40**. |
| Heart | Saves the product to [favourites](https://docs.sparklayer.io/help/ordering/favourites.md). |
| **SKU** | The product code, and the barcode, if you've turned them on. See [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md#customise-product-cards). |

### Cards line up in a grid

On a collection page, the cards in a row line up. Each card's price, volume break, stock, variants, quantity and **Add** button sit at the same height as its neighbours'. This holds even when one product has 2 variant lists and another has none. A card on its own, outside a grid, is laid out as a simple column. 

To see what customers see, explore the product interfaces in [our interactive demo](https://www.figma.com/proto/5FPCY5hSGl7mlwjsjMZI2t/SparkLayer-Interfaces?page-id=0%3A1\&type=design\&node-id=86-36708\&viewport=554%2C-398%2C0.33\&t=34VlPwbCqpvQOTsh-8\&scaling=min-zoom\&starting-point-node-id=35%3A7920\&hide-ui=1).

## Add the interface to your store

This section is for you, the merchant. To have our team install the product card interface for you, free of charge, click **Request installation** at **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app. Or add it yourself:

**Shopify:**

There are 2 ways to add the product card interface on Shopify:

1. **Theme setup:** go to **Home > Setup > Theme setup** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Setup > Theme setup** in the Shopify app. Under **Optional blocks**, click **Add** next to **Product card block**. Shopify's theme editor opens at that block: put it where you want the interface to appear, and save. See [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md).

   **More detail**

   In the theme editor, the block is called **SparkLayer - Product Card**. You can also add it yourself: go to **Online Store > Themes** ([open in the Shopify admin](https://admin.shopify.com/themes)), click **Customize**, open a collection or product page and add the block.

2. **Code (for your developer):** if your theme doesn't support app blocks, or you'd rather use code, add this line to the file that renders product cards on your collection pages:

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

**Other platforms:**

Your developer adds this line to the template that renders product cards on your collection pages:

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

Replace `product.id` with the variable your platform uses for the product's ID. See the install guide for your platform under [Platforms](https://docs.sparklayer.io/help/platforms.md).

Once it's added, every signed-in B2B customer sees the interface on your product cards and can start ordering.

## Change what it shows

You can change what the product card shows. It can show stock, the SKU or the barcode, hide variant drop-downs, or show products as table rows (quick buy mode). See [Customise product cards](https://docs.sparklayer.io/help/storefront/product-display.md#customise-product-cards) in Product display.

## FAQs

**Can I use the product card interface on Wix?**

**Wix only:**

No. Wix doesn't support the product card interface, so prices on gallery and other product listing pages are hidden for B2B customers. Customers see their prices and order on product pages instead. See [Wix limitations](https://docs.sparklayer.io/help/platforms/wix/limitations.md).


---

# Product price

URL: https://docs.sparklayer.io/help/storefront/interfaces/product-price

Show signed-in B2B customers their own price or the RRP anywhere on your product or collection pages with the SparkLayer product price snippet.

> **Quick summary**
>
> - The product price interface shows a signed-in B2B customer their own price, or the RRP, for a product anywhere on your store, such as collection (category) pages or product pages.
> - Use it alongside the other product interfaces, or instead of them when you want full control over where prices appear.
> - Your developer or agency adds it with one line of code per price in your theme: `spark-product-price` for the B2B price and `spark-product-rrp` for the RRP.
> - It's included on every plan. On an existing theme, you also need to hide the prices your theme shows to B2B customers.

## How it works

The product price interface is one of SparkLayer's [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md). It only shows a price: unlike the [product card](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) and [product detail](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) interfaces, there's no quantity box or "add to cart" button. For example, a collection page can show customers "$9.99 RRP: $19.99" under each product name, using your theme's own layout.

There are 2 prices you can show:

| Price | What it shows |
| --- | --- |
| **B2B pricing** | The signed-in customer's own B2B price. |
| **RRP pricing** | The RRP you've set for the product. See [How prices are shown](https://docs.sparklayer.io/help/pricing/pricing-display.md). |

To see what customers see, explore the product interfaces in [our interactive demo](https://www.figma.com/proto/5FPCY5hSGl7mlwjsjMZI2t/SparkLayer-Interfaces?page-id=0%3A1\&type=design\&node-id=86-36708\&viewport=554%2C-398%2C0.33\&t=34VlPwbCqpvQOTsh-8\&scaling=min-zoom\&starting-point-node-id=35%3A7920\&hide-ui=1).

## Add the interface to your store

This section is for your developer or agency. They add the line for each price you want to your theme's template, for example your product page or product card template. You can use both together, and place them anywhere on your store.

```html
<!-- Use this to show the B2B pricing -->
<spark-product-price parent-id="{{ product.id }}"></spark-product-price>
```

```html
<!-- Use this to show the RRP pricing -->
<spark-product-rrp parent-id="{{ product.id }}"></spark-product-rrp>
```

If your platform uses a different variable for the product's ID, replace `product.id` with it. See the install guide for your platform under [Platforms](https://docs.sparklayer.io/help/platforms.md).

Once it's added, every signed-in B2B customer sees their prices.

On an existing theme, also hide the theme's own prices and anything else you don't want B2B customers to see. See the [Frontend integration guide](https://docs.sparklayer.io/developers/frontend.md).

## Change what it shows

To show RRP, quantity pricing or unit prices, see [How prices are shown](https://docs.sparklayer.io/help/pricing/pricing-display.md). For other options, see [Storefront](https://docs.sparklayer.io/help/storefront.md).


---

# Custom slots (targets)

URL: https://docs.sparklayer.io/help/storefront/interfaces/custom-slots

Add your own messages, promotions and links inside SparkLayer's My Account, My Cart and checkout with custom slots, with ready-made examples to copy.

> **Quick summary**
>
> - Custom slots (also called targets) let you show B2B customers your own messages inside SparkLayer's [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md). For example, a promotion at the top of My Account or a message on each cart line.
> - There are 8 slots, covering My Account, My Cart, each cart line, the **Shipping** and **Review & Pay** checkout steps, the order complete screen and the purchase summary.
> - You turn a slot on without code at **Storefront > Options > Custom slots** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Custom slots** in the Shopify app. The content itself is a small block of HTML (a `<template>` element) in your theme, so your developer or agency usually adds it.
> - Slot content only appears inside SparkLayer's interfaces, so only signed-in B2B customers see it. Keep your Core Script up to date 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 to get every slot.

## How it works

Your customers see slot content as part of SparkLayer's interfaces, in a fixed place such as the top of My Account. Behind the scenes, each slot has an ID, such as `spark-slot-my-account`.

You turn on the slots you want, at **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app or in your Core Script. Your developer then adds a `<template>` element with the same ID anywhere in your theme. SparkLayer takes the content of the template and shows it in that slot's place in the interface.

How slot content reaches the storefront:

1. **Turn the slot on**: In Custom slots on the Storefront Options page, or in showSlots in the Core Script
2. **Your theme**: Add a template element with the slot's ID
3. **SparkLayer interface**: Shows the template's content in the slot

You can use slots for things like:

| Use | Example |
| --- | --- |
| **Promotional content** | A message in the [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) that customers see as soon as they sign in, such as announcing a new product line. |
| **Adding links** | Links in the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md), such as downloadable CSV templates. |
| **Order complete content** | Offers or promotions when a customer [completes an order](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md#complete-step), such as asking for a rating. |

With some extra code in your theme, the content can also change for each customer or order:

| Use | Example |
| --- | --- |
| **Customer-specific** | Show different content depending on who the customer is and which [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md) they're in, such as a promotion for the `VIP` group. |
| **Order-specific** | Show a message based on the order contents or total, such as encouraging customers to add more products when the order is under $100. |

## Slot locations

Each slot appears in one place in the interfaces:

| Slot | Where it appears | ID |
| --- | --- | --- |
| **My Account** | At the top of the [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md), above **Recent Activity**. | `spark-slot-my-account` |
| **My Order** | At the top of the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md), below the search box and above the products. | `spark-slot-my-cart` |
| **Order Complete** | On the order complete screen, below the **Thank you for your order!** message. | `spark-slot-order-complete` |
| **Cart Shipping Step** | On the **Shipping** step of the checkout. | `spark-slot-cart-shipping-step` |
| **Cart Payment Step** | On the payment (**Review & Pay**) step of the checkout. | `spark-slot-cart-payment-step` |
| **Purchase Summary Header** | Above the purchase summary when a customer views a purchase. | `spark-slot-purchase-summary-header` |
| **Purchase Summary Footer** | Below the purchase summary when a customer views a purchase. | `spark-slot-purchase-summary-footer` |
| **Cart Line Item** | Below each product line in My Cart. | `spark-slot-my-cart-line-item` |

In the My Account interface, you can also choose where the My Account slot sits among the other sections. See [Reorder or hide sections](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md#reorder-or-hide-sections).

You can't add a slot anywhere else, or move one. For what else you can change in the widgets, and what needs a developer, see [What you can and can't change](https://docs.sparklayer.io/help/storefront/what-you-can-change.md).

## Before you start

- **Edit access to your theme code** (or a developer who has it), to add the slot templates.
- **An up-to-date Core Script**, so every slot on this page is available. Check it 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.
- **A signed-in B2B customer account** to check how your content looks, as slot content isn't shown to anyone else.

## Turn on the slots

Turn on each slot you want to use. You don't need code:

1. Go to **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app and open **Custom slots**.
2. Click **Add slot** and choose the slot you want to use. Repeat for each slot.
3. Click **Save and publish**. See [Storefront options](https://docs.sparklayer.io/help/storefront/storefront-options.md#custom-slots).

**Turn on the slots in the Core Script (for developers)**

Instead of Storefront options, add `showSlots` to the `display` section of your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting), listing the IDs of the slots you want to use. This example turns on all 8:

```javascript title="Core Script"
display: {
  showSlots: [
    'spark-slot-my-account',
    'spark-slot-my-cart',
    'spark-slot-order-complete',
    'spark-slot-cart-shipping-step',
    'spark-slot-cart-payment-step',
    'spark-slot-purchase-summary-header',
    'spark-slot-purchase-summary-footer',
    'spark-slot-my-cart-line-item',
  ],
},
```

## Add content to a slot

This step is for your developer, or whoever edits your theme's code. For each slot you've turned on, add a `<template>` element to your theme with the slot's ID as its `id`, and put your content inside it. For a ready-made styled message, see [Examples you can use](#examples-you-can-use).

**Example templates for each slot**

```html
<!-- Example code for the My Account slot -->
<template id="spark-slot-my-account">
   <div class="my-content">
       Content here will show in the My Account section.
   </div>
</template>

<!-- Example code for the My Cart slot -->
<template id="spark-slot-my-cart">
   <div class="my-content">
       Content here will show in the My Order section.
   </div>
</template>

<!-- Example code for the My Order slot -->
<template id="spark-slot-order-complete">
   <div class="my-content">
       Content here will show in the Order Complete section.
   </div>
</template>

<!-- Example code for the Cart Shipping Step slot -->
<template id="spark-slot-cart-shipping-step">
   <div class="my-content">
       Content here will show in the Cart Shipping Step section.
   </div>
</template>

<!-- Example code for the Cart Payment Step slot -->
<template id="spark-slot-cart-payment-step">
   <div class="my-content">
       Content here will show in the Cart Payment Step section.
   </div>
</template>

<!-- Example code for the Purchase Summary Header slot -->
<template id="spark-slot-purchase-summary-header">
   <div class="my-content">
       Content here will show in the Purchase Summary Header section.
   </div>
</template>

<!-- Example code for the Purchase Summary Footer slot -->
<template id="spark-slot-purchase-summary-footer">
   <div class="my-content">
       Content here will show in the Purchase Summary Footer section.
   </div>
</template>
```

Put the templates in your theme's main layout file (for example `layout/theme.liquid` on Shopify), or anywhere else that's easy to find and update.

The content can be a line of text, or full HTML with CSS, images and other elements. Only your B2B customers see it:

- Content in a template only shows in its slot. For example, the `spark-slot-my-cart` template shows in the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md).
- Templates aren't shown anywhere else on your store, and customers who aren't signed in never see them.

> **Only change your own slot content**
>
> You can only change the elements inside your own slot templates. Don't try to change SparkLayer's own interface elements (the DOM): their structure and selectors change regularly, so any code that relies on them will stop working.

## Examples you can use

These examples are for your developer, ready to copy and adapt. The Liquid examples (using `{{ }}` and `{% %}`) are for Shopify.

**Show a custom HTML message with coloured backgrounds**

```html
    <!-- Template element for My Order Interface-->

    <template id="spark-slot-my-cart">

        <style>
          .b2b-message-cart {
              background: #3875F3;
              color: #fff;
              padding: 12px;
              border-radius: 8px;
              text-align: center
          }
          .b2b-message-cart a {
              color: #fff;
              text-decoration: underline
          }
        </style>
        <div class="b2b-message-cart">
          🎉 For this week only, get an extra 10% off your B2B order! 🎉
        </div>

    </template>

    <!-- Template element for My Account Interface-->

    <template id="spark-slot-my-account">

        <style>
          .b2b-message-account {
              background: #FF4CBF;
              color: #fff;
              padding: 12px;
              border-radius: 8px;
              text-align: center
          }
          .b2b-message-account a {
              color: #fff;
              text-decoration: underline
          }
        </style>
        <div class="b2b-message-account">
          👋 Welcome back, Claire! Don't forget to check our <a href="link-here">latest special offers here</a>!
        </div>

    </template>

    <!-- Template element for Order Complete -->

    <template id="spark-slot-order-complete">

        <style>
          .b2b-message-complete {
              background: #FF4CBF;
              color: #fff;
              padding: 12px;
              border-radius: 8px;
              text-align: center
          }
          .b2b-message-complete a {
              color: #fff;
              text-decoration: underline
          }
        </style>
        <div class="b2b-message-complete">
          😊 Whilst you're here, would you be able to <a href="link-here">leave feedback on your B2B experience</a>? It would really help us improve our website!
        </div>

    </template>

```

**Show a custom HTML message with gradient coloured backgrounds**

This shows a bordered message with a soft gradient background and a "NEW!" label, for example "Show content here for your B2B customers, such as new promotions".

```html
  <template id="spark-slot-my-account">

        <style>
          .b2b-message-account {
            position: relative;
            overflow: hidden;
            padding: 1em;
            border: 2px solid #a68eee;
            border-radius: 6px;
            text-align: center;
            display: flex;
            column-gap: 8px;
            color: #444;
            text-align: left
          }
          .b2b-message-account:after {
            background: linear-gradient(136deg, #54ff96 0%, #80c0ff 48.78%, #f860ff 100%);
            pointer-events: none;
            position: absolute;
            top: 0;
            left: 0;
            width: 100%;
            background-position: 50%;
            background-repeat: no-repeat;
            content: "";
            background-size: auto 100%;
            z-index: 1;
            background-size: 800px;
            height: 60px;
            filter: blur(100px);
            opacity: 0.9;

          }
          .b2b-message-account a {
              color: #5b36f5;
              text-decoration: underline
          }

          .b2b-message-account span {
            background: linear-gradient(54deg, #5B36F5 5.48%, #FF4CBF 44.27%, #3875F3 75.97%, #5B36F5 94.09%);
            display: inline-flex;
            text-transform: uppercase;
            font-size: 11px;
            border-radius: 4px;
            align-items: center;
            padding: 0 6px;
            color: #fff;
            font-weight: 600;
          }
        </style>

        <div class="b2b-message-account">
          <span>NEW!</span>
          Show custom content here for specific customers, such as new promotions 🚀 
        </div>

    </template>

   <template id="spark-slot-my-cart">

        <style>
          .b2b-message-account {
            position: relative;
            overflow: hidden;
            padding: 1em;
            border: 2px solid #a68eee;
            border-radius: 6px;
            text-align: center;
            display: flex;
            column-gap: 8px;
             color: #444;
            margin: -6px 0 0 ;
            text-align: left
          }
          .b2b-message-account:after {
            background: linear-gradient(136deg, #54ff96 0%, #80c0ff 48.78%, #f860ff 100%);
            pointer-events: none;
            position: absolute;
            top: 0;
            left: 0;
            width: 100%;
            background-position: 50%;
            background-repeat: no-repeat;
            content: "";
            background-size: auto 100%;
            z-index: 1;
            background-size: 800px;
            height: 60px;
            filter: blur(100px);
            opacity: 0.9;

          }
          .b2b-message-account a {
              color: #5b36f5;
              text-decoration: underline
          }

          .b2b-message-account span {
            background: linear-gradient(54deg, #5B36F5 5.48%, #FF4CBF 44.27%, #3875F3 75.97%, #5B36F5 94.09%);
            display: inline-flex;
            text-transform: uppercase;
            font-size: 11px;
            border-radius: 4px;
            align-items: center;
            padding: 0 6px;
            color: #fff;
            font-weight: 600;
            text-align: left
          }
        </style>
        <div class="b2b-message-account">
          <span>NEW!</span>
          Show content to your B2B customers such as promoting free shipping 🚀 
        </div>

    </template>

  <template id="spark-slot-order-complete">

        <style>
          .b2b-message-account {
            position: relative;
            overflow: hidden;
            padding: 1em;
            border: 2px solid #a68eee;
            border-radius: 6px;
            text-align: center;
            display: flex;
            column-gap: 8px;
            color: #444;
            text-align: left
          }
          .b2b-message-account:after {
            background: linear-gradient(136deg, #54ff96 0%, #80c0ff 48.78%, #f860ff 100%);
            pointer-events: none;
            position: absolute;
            top: 0;
            left: 0;
            width: 100%;
            background-position: 50%;
            background-repeat: no-repeat;
            content: "";
            background-size: auto 100%;
            z-index: 1;
            background-size: 800px;
            height: 60px;
            filter: blur(100px);
            opacity: 0.9;

          }
          .b2b-message-account a {
              color: #5b36f5;
              text-decoration: underline
          }

          .b2b-message-account span {
            background: linear-gradient(54deg, #5B36F5 5.48%, #FF4CBF 44.27%, #3875F3 75.97%, #5B36F5 94.09%);
            display: inline-flex;
            text-transform: uppercase;
            font-size: 11px;
            border-radius: 4px;
            align-items: center;
            padding: 0 6px;
            color: #fff;
            font-weight: 600;
          }
        </style>
        <div class="b2b-message-account">
          <span>NEW!</span>
          When an order is placed, you can include further content here.
        </div>

    </template>

```

**Show a message using ready-made SparkLayer components (e.g. "success")**

```html
    <!-- 

    You can change the message type using the following

    type="success"
    type="info"
    type="warn"
    type="error"

    -->

    <!-- Template element for My Order Interface-->

    <template id="spark-slot-my-cart">
       <spark-message 
          type="success"
          title="Title here"
          message="Message here">
        </spark-message>    
    </template>

    <!-- Template element for My Account Interface-->

    <template id="spark-slot-my-account">
       <spark-message 
          type="info"
          title="Title here"
          message="Message here">
        </spark-message>   
    </template>

    <!-- Template element for Order Complete -->

    <template id="spark-slot-order-complete">
       <spark-message 
          type="warn"
          title="Title here"
          message="Message here">
        </spark-message>         
    </template>

```

**Show a message that shows customer metafields**

```html
    <!-- 

   Replace custom.field_name with the metafield namespace and key

    -->

    <!-- Template element for My Account Interface-->
    {% if customer.metafields.custom.field_name %}
       <template id="spark-slot-my-account">
          Your message here.
          You can output a metafield like this
          {{ customer.metafields.custom.field_name }}
      </template>
    {%  endif %}
```

**Show a message that includes the customer's name**

```html

    <!-- Template element for My Order Interface-->
    <template id="spark-slot-my-cart">
       Hello {{ customer.name }}, here's a message for you.
    </template>

    <!-- Template element for My Account Interface-->
    <template id="spark-slot-my-account">
      Hello {{ customer.name }}, here's a message for you.
    </template>

    <!-- Template element for Order Complete -->
    <template id="spark-slot-order-complete">
      Hello {{ customer.name }}, here's a message for you.
    </template>
```

**Show a message based on the Shopify tag assigned to a customer (e.g. b2b-vip)**

**Shopify only:**

```html
<template id="spark-slot-my-cart">

{% for tag in customer.tags %}

 {% if tag == "b2b-group-1" %}
   As a Group 1 customer, you qualify for special B2B pricing!
 {% elsif tag == "b2b-group-2" %}
   As a Group 2 customer, you qualify for special B2B pricing!
  {% else %}  
   Message to show for regular B2B customers
 {% endif %} 

{% endfor %}

</template>
```

**Show a message that includes text and an image**

```html
  <!-- Template element for My Order Interface-->
    <template id="spark-slot-my-cart">
      <p>Here is a message</p>
      <img src="link-to-image" style="max-width: 100%">
    </template>

    <!-- Template element for My Account Interface-->
    <template id="spark-slot-my-account">
      <p>Here is a message</p>
      <img src="link-to-image" style="max-width: 100%">
    </template>

    <!-- Template element for Order Complete -->
    <template id="spark-slot-order-complete">
      <p>Here is a message</p>
      <img src="link-to-image" style="max-width: 100%">
    </template>
```

**Show a message at a cart line-item level**

This shows a message under a product line in My Cart that refers to the product, for example "MUG-CAT - example-ceramic-mug requires special handling." It uses the product's SKU and slug.

For slots that need different messages or behaviour on each line, use web components to keep each line's state separate, as in the example below.

This slot can read these `data-` attributes from its parent element, using `this.parentNode.dataset`:

- `data-sku`
- `data-slug`
- `data-spark-id`
- `data-platform-id`
- `data-item-key`

```html
  <script>
        class LineItemInfo extends HTMLElement {
          connectedCallback() {
            let data = this.parentNode.dataset;
            this.innerHTML = `<p class="line-item-info-messsage">${data.sku} - ${data.slug} requires special handling.</p>`;
          }
        }
        customElements.define('line-item-info', LineItemInfo);
      </script>
      <template id="spark-slot-my-cart-line-item">
        <style>
          .line-item-info-messsage {
              background: #f5f5f5;
              padding: 8px;
              border-radius: 4px;
          }
        </style>
        <line-item-info></line-item-info>
      </template>
```

As with every slot, only change elements inside your own template, not SparkLayer's own elements.

Found a good use for custom slots? Tell our team at [product@sparklayer.io](mailto:product@sparklayer.io).


---

# B2B Catalogs

URL: https://docs.sparklayer.io/help/storefront/b2b-catalogs
Applies to: Shopify

Show or hide Shopify products for B2B and retail customers with tags, using the free B2B Catalogs app. Install it, enable it on a theme and see how it works.

> **Quick summary**
>
> - With [B2B Catalogs](https://apps.shopify.com/sparklayer-b2b-catalogs), B2B and retail (B2C) customers each see only the products meant for them. You choose which with tags in your Shopify admin. No code needed.
> - It's a standalone app, free on every SparkLayer plan, including the free plan. It's only available for Shopify.
> - You turn it on for each theme from the app in your Shopify admin. There's no limit to how many themes you can enable it on.
> - Showing different products or variants to different [customer groups](https://docs.sparklayer.io/help/glossary.md#customer-group) also needs the [SparkLayer Wholesale app](https://docs.sparklayer.io/help/platforms/shopify/install.md). See [Catalogs per customer group](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-advanced-catalogs.md).

## How it works

A product hidden from a customer doesn't show to them on product pages, collection pages or in store search. If a customer opens a hidden product's URL directly, they see an [access denied page](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-access-denied-view.md) instead. Hiding happens as the page loads, so a hidden product can still take a place in a collection grid and count towards product and filter totals: see [Collection grids, search and filter counts](https://docs.sparklayer.io/help/storefront/b2b-catalogs/limitations.md#grids-search-and-filter-counts).

To make this work, B2B Catalogs changes the files of each theme you enable it on, so the theme can check who's browsing.

How a customer's tags decide what they see:

1. **Customer tags**: A customer tagged `b2b` is a B2B customer. Everyone else is a retail (B2C) customer.
2. **Product tags**: `b2b-only` products are shown only to B2B customers. `b2c-only` products are shown only to retail customers.
3. **Customer group rules**: If you need it, the `sparklayer.settings` metafield hides variants from particular B2B customer groups, such as customers tagged `b2b-vip`. It doesn't hide anything from retail customers.
4. **What they see**: Hidden products drop out of product pages, collections and search. A direct link shows the access denied page.

To set up the tags, see [Show or hide products](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-your-catalogs.md).

### B2B Catalogs or B2B-only content

B2B Catalogs hides whole products from B2B or retail customers, and variants from B2B customer groups. It can't hide a single variant from retail customers: see [Variants and retail shoppers](https://docs.sparklayer.io/help/storefront/b2b-catalogs/limitations.md#variants-and-retail-shoppers). To change what B2B customers see in other ways, use one of SparkLayer's other options:

| Option | Use it to | How |
| --- | --- | --- |
| B2B Catalogs | Hide whole products from B2B or retail customers across your store, and variants from B2B customer groups | Tags in your Shopify admin, no code |
| [Shopify B2B-only content](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-only-content.md) | Hide prices from signed-out visitors, show B2B-only content, menus and banners, or redirect pages | Liquid code in your theme |
| [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md) | Change what SparkLayer's product interfaces show signed-in B2B customers, including hiding a variant or stopping it being added to the cart | Settings in your theme's code and the `sparklayer.settings` metafield |

`display: false` in the `sparklayer.settings` metafield on its own only hides a product inside SparkLayer's views, such as search, quick order and the cart. Your theme's collection pages, product pages and featured sections need B2B Catalogs. See [What hides what](https://docs.sparklayer.io/help/storefront/product-settings.md#what-hides-what), and [Hide products from customers](https://docs.sparklayer.io/help/guides/hide-products.md) for every option.

## Install and enable B2B Catalogs

1. Install [B2B Catalogs](https://apps.shopify.com/sparklayer-b2b-catalogs) from the Shopify App Store. The app guides you through setup.
2. Open the app in your Shopify admin. Under **Enable on your theme**, choose a theme from the drop-down and click **Enable**.
3. Tag your customers and products. See [Show or hide products](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-your-catalogs.md).

**More detail**

B2B Catalogs adds a snippet to the theme, `snippets/sparklayer-b2b-catalogs-access-denied.liquid`, which shows the [access denied page](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-access-denied-view.md). If the app can't change a theme because of invalid Liquid syntax, see [B2B Catalogs limitations](https://docs.sparklayer.io/help/storefront/b2b-catalogs/limitations.md#invalid-liquid-syntax).

## Enable or disable it on other themes

Once you've enabled B2B Catalogs on one theme, the app lists all your themes under **Enable on your theme**. Each theme shows its **Type** (**Published** or **Unpublished**) and **Status** (**Enabled** or **Disabled**).

1. Open B2B Catalogs in your Shopify admin.
2. Find the theme and click **Enable** or **Disable** in the **Action** column.

You can enable it on published and unpublished themes, and on as many themes as you like.

**More detail**

Disabling B2B Catalogs on a theme removes its visibility rules from that theme, along with any changes you've made to the access denied page. Before you uninstall the app, disable it on every theme: see [Uninstall B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs/removing-b2b-catalogs.md).

## Troubleshooting

**Diagnose: Product showing to the wrong customers?** Check which tool should hide it.

1. **What’s happening?** Pick the closest match.
   - A product shows to customers who shouldn’t see it: go to question 2
   - A product is hidden from customers who should see it: go to fix A (Check the product itself)
2. **Where do they see it?** SparkLayer’s own views and your theme’s pages are hidden by different tools.
   - In SparkLayer’s quick order, search or cart: go to question 3
   - On collection, product or search pages: go to question 4
   - In a section such as a featured collection: go to question 5
3. **Does the variant’s `sparklayer.settings` metafield set `"display": false` for the customer’s group?** Use the group’s handle, for example `base`. Entries for a group override the `base` entry. Where to look: Products > select a variant > Metafields (Shopify admin).
   - Yes: go to question 6
   - No: go to fix B (Add a rule for that group)
4. **Is the free B2B Catalogs app installed and enabled on your live theme?** The visibility metafield only hides products inside SparkLayer. Hiding them from your theme’s pages needs B2B Catalogs. Where to look: Online Store > Themes (Shopify admin).
   - Yes: go to question 7
   - No / not sure: go to fix C (Install B2B Catalogs and enable it on your live theme)
5. **Is the free B2B Catalogs app installed and enabled on your live theme?** Sections such as featured collections are your theme’s, so only B2B Catalogs can hide products in them. Where to look: Online Store > Themes (Shopify admin).
   - Yes: go to fix D (Turn B2B Catalogs off and on again on your live theme)
   - No / not sure: go to fix C (Install B2B Catalogs and enable it on your live theme)
6. **Is the JSON written with straight quotes and valid formatting?** Curly quotes from a word processor, or a missing comma or bracket, break every rule in the value. Paste it into a JSON checker if unsure.
   - Yes: go to fix E (Everything checks out)
   - No / not sure: go to fix F (Fix the JSON)
7. **Is the product tagged, for example `b2b-only`, or in a catalog for the right groups?** `b2b-only` hides a product from retail shoppers. `b2c-only` hides it from B2B customers. Where to look: Products > select the product (Shopify admin).
   - Yes: go to fix D (Turn B2B Catalogs off and on again on your live theme)
   - No: go to fix G (Tag the product)

**Fixes**

- **A. Check the product itself** A product that should show but doesn’t usually has a SKU, status, sales channel or price list issue. Next: Product missing, no B2B price or “Unavailable”?
- **B. Add a rule for that group** Add an entry for the customer’s group with `"display": false` to the variant’s `sparklayer.settings` metafield. To hide it from every B2B customer, use the `base` group. Where: Products > select a variant > Metafields (Shopify admin). See [Product settings](https://docs.sparklayer.io/help/storefront/product-settings.md).
- **C. Install B2B Catalogs and enable it on your live theme** Without it, tags such as `b2b-only` and the visibility metafield can’t hide products on your theme’s pages. Install the free app, then enable it on your live (published) theme. See [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md).
- **D. Turn B2B Catalogs off and on again on your live theme** After app updates or theme changes, the live theme may not have the latest B2B Catalogs code. Turn it off and on again on the live theme. If the product still shows in a section, send us the page link. See [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md).
- **E. Everything checks out** Your setup looks right, so we'll take it from here. Send us your answers with the product link and the customer’s email.
- **F. Fix the JSON** Retype the quotes as straight quotes, correct the formatting and save. Copy an example from Product settings as a starting point. See [Product settings examples](https://docs.sparklayer.io/help/storefront/product-settings.md).
- **G. Tag the product** Add `b2b-only` to keep it from retail shoppers, or set up a catalog for the groups that should see it. Where: Products > select the product (Shopify admin). See [Catalogs per customer group](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-advanced-catalogs.md).

**Why do b2b-only products show in a featured collection?**

After an app update or a change to your theme, a section such as a featured collection can start showing `b2b-only` products. Open B2B Catalogs, click **Disable** on your live (published) theme, then click **Enable** again. Disabling removes your changes to the [access denied page](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-access-denied-view.md), so keep a copy of them first.

**Why don't my b2b-only and b2c-only tags do anything?**

The tags only work while B2B Catalogs is installed and enabled on your live (published) theme. Enabling it on an unpublished theme doesn't change your live store. Check the theme's **Status** shows **Enabled** under **Enable on your theme**.

**Can I hide a whole collection?**

Not with B2B Catalogs: it hides products, not collections. A third-party Shopify app can restrict who can open a collection's URL.

## Get help

Email [support@sparklayer.io](mailto:support@sparklayer.io), or click the message icon in the B2B Catalogs app. See [Contact support](https://docs.sparklayer.io/help/support.md) for when we're available and what to include.

## Next steps

- [Show or hide products](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-your-catalogs.md): Mark customers as B2B and products as B2B-only or B2C-only with Shopify tags.
- [Catalogs per customer group](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-advanced-catalogs.md): Show or hide variants for particular customer groups with the sparklayer.settings metafield.
- [Customise the access denied page](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-access-denied-view.md): Change what customers see when they open a product that's hidden from them.
- [B2B Catalogs limitations](https://docs.sparklayer.io/help/storefront/b2b-catalogs/limitations.md): Variant limits, carts, permalinks, third-party apps and theme syntax errors.
- [B2B Catalogs FAQs](https://docs.sparklayer.io/help/storefront/b2b-catalogs/faqs.md): SEO and sitemaps, pricing, setup and disabling the app on a theme.
- [Uninstall B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs/removing-b2b-catalogs.md): Disable the app on every theme, then uninstall it safely.


---

# Show or hide products

URL: https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-your-catalogs
Applies to: Shopify

Tag Shopify customers as b2b and products as b2b-only or b2c-only to control who sees each product with B2B Catalogs, and hide variants per customer group.

> **Quick summary**
>
> - B2B Catalogs decides which products each customer sees from tags on customers and products in your Shopify admin.
> - Tag a customer `b2b` to make them a B2B customer. Tag a product `b2b-only` to show it only to B2B customers, or `b2c-only` to show it only to retail (B2C) customers.
> - To hide variants from particular customer groups, use the `sparklayer.settings` metafield. This needs the [SparkLayer Wholesale app](https://docs.sparklayer.io/help/platforms/shopify/install.md) as well.

## How it works

Each customer sees the products tagged for them, and products with no tag. B2B Catalogs works this out from customer tags, product tags and variant metafields:

| What you tag | Tag or metafield | What it does |
| --- | --- | --- |
| Customer | `b2b` | Marks the customer as a B2B customer. |
| Product | `b2b-only` | Hides the product from retail (B2C) customers. Only customers tagged `b2b` see it. |
| Product | `b2c-only` | Hides the product from B2B customers. Only retail (B2C) customers see it. |
| Variant | `sparklayer.settings` | Hides the product for a customer group when every variant is hidden for that group. See [Hide products from a customer group](#hide-products-from-a-customer-group). |

Products with neither tag are shown to everyone.

## Mark a customer as B2B

1. In your Shopify admin, go to **Customers** ([open in the Shopify admin](https://admin.shopify.com/customers)) and open the customer.
2. Add the tag `b2b` and click **Save**.

**More detail**

This is the same `b2b` tag SparkLayer uses to identify [B2B customers](https://docs.sparklayer.io/help/glossary.md#b2b-customer), so customers you've already set up for SparkLayer don't need another tag.

## Make a product B2B-only or B2C-only

1. In your Shopify admin, go to **Products** ([open in the Shopify admin](https://admin.shopify.com/products)) and open the product.
2. Add the tag `b2b-only` or `b2c-only` and click **Save**.

**More detail**

A hidden product is hidden on product pages, collection pages and in store search. If a customer opens its URL directly, they see the [access denied page](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-access-denied-view.md). Products already in a customer's cart stay there: see [B2B Catalogs limitations](https://docs.sparklayer.io/help/storefront/b2b-catalogs/limitations.md).

## Hide products from a customer group

This needs the [SparkLayer Wholesale app](https://docs.sparklayer.io/help/platforms/shopify/install.md) as well as B2B Catalogs.

To hide a whole product from one customer group, hide every one of its variants from that group. You do this with [SparkLayer's variant-level selling rules](https://docs.sparklayer.io/help/storefront/product-settings.md#available-product-settings) in the `sparklayer.settings` metafield, by setting `display` to `false` for the group.

When all of a product's variants are hidden for the signed-in customer's customer group, B2B Catalogs hides the product too.

For how to write the rules, see [Catalogs per customer group](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-advanced-catalogs.md). To write them for many products at once, or have your AI assistant apply them, see [Hide products from customers](https://docs.sparklayer.io/help/guides/hide-products.md).


---

# Catalogs per customer group

URL: https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-advanced-catalogs
Applies to: Shopify

Show or hide product variants for particular B2B customer groups with sparklayer.settings metafield rules, the base group and b2b- customer tags in Shopify.

> **Quick summary**
>
> - With catalogs per customer group, some products are only visible to particular B2B [customer groups](https://docs.sparklayer.io/help/glossary.md#customer-group). You show or hide them variant by variant, for each group.
> - You set the rules in the `sparklayer.settings` variant [metafield](https://docs.sparklayer.io/help/glossary.md#metafields), an extra field on each variant in your Shopify admin. A [form on this page](#set-up-variant-visibility) writes the rule for you to copy.
> - You also need the [SparkLayer Wholesale app](https://docs.sparklayer.io/help/platforms/shopify/install.md) for Shopify.
> - Rules only apply to signed-in B2B customers. To hide a product from retail shoppers and signed-out visitors too, also tag it `b2b-only`.

## How it works

Every variant is visible to every customer group by default. To hide a variant from a group, you add a rule to the variant's `sparklayer.settings` metafield. The rule names the customer group and sets `display` to `false`. If all of a product's variants are hidden for a customer, they don't see the product at all.

How a variant rule hides a product:

1. **Customer tag**: The customer's tag, such as `b2b-vip`, places them in the `vip` customer group.
2. **Variant rule**: The variant's `sparklayer.settings` rule for `vip`, or for `base`, sets `display` to `true` or `false`.
3. **Product**: If every variant is hidden for the customer, the whole product is hidden.

> **Hiding from retail shoppers too?**
>
> Customer group rules work without a `b2b-only` tag, but they only apply to signed-in B2B customers. To hide the product from retail shoppers and signed-out visitors as well, tag it `b2b-only`.

For what each method hides, across SparkLayer's views and your theme's pages, see [What hides what](https://docs.sparklayer.io/help/storefront/product-settings.md#what-hides-what).

## Set up variant visibility

1. Create the `sparklayer.settings` variant metafield. See [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md#set-product-settings-for-a-customer-group) for how to add it.
2. Optional. To hide the product from retail shoppers and signed-out visitors as well, tag it `b2b-only` in your Shopify admin.
3. In the form below, enter each customer group's [handle](#find-the-group-name) and choose **Yes** or **No** under **Show the product**. It writes the rule for you.
4. Click **Copy**, open the variant, paste the value into the `sparklayer.settings` metafield and click **Save**.

**Lots of products? Fill them in one table (Shopify):** in your Shopify admin, go to **Products**, tick the products and click **Edit products**. Click **Columns**, tick the SparkLayer field under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

To hide the same products from one or more groups, the form in [Hide products from customers](https://docs.sparklayer.io/help/guides/hide-products.md) writes the rule and can hand it to your AI assistant to apply to every product.

**More detail**

The metafield accepts a list of rules. Each rule names a customer group and whether the variant is displayed for that group:

```json
[
{
"customer_group": "group-name",
"display": true / false
}
]
```

`display` is one of the [sparklayer.settings product settings](https://docs.sparklayer.io/help/storefront/product-settings.md#available-product-settings), which also cover pack sizes, quantity limits and whether a variant can be added to the cart.

## Find the group handle

In the metafield, use the customer group's handle, not its name or its Shopify tag. To find it, 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, click the group's name and find its **Handle (or ID)**. A customer's Shopify tag is `b2b-` followed by the handle, so the handle is the tag without its first `b2b-`:

| Customer tag in Shopify | Handle in the metafield |
| --- | --- |
| `b2b-vip` | `vip` |
| `b2b-customer-group-b` | `customer-group-b` |
| `b2b-b2b-uk` | `b2b-uk` |

If a handle starts with `b2b-`, keep it. Only remove the first `b2b-` from the tag.

For how customers are matched to groups, see [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md).

## Use the base group

The special customer group `base` sets the default visibility for all B2B customers. Use it to hide a product from everyone, then show it to particular groups. For an example, see [Hide a product from all B2B customers except one group](#hide-a-product-from-all-b2b-customers-except-one-group).

Setting `base` to `false` hides the product for all B2B customer groups, even if the product is tagged `b2b-only`. An entry for a specific group overrides `base` for that group, so you can show it to that group again.

If you also set a pack size or a quantity limit, put it in the same `sparklayer.settings` value, inside each group's entry. When a variant has a `sparklayer.settings` value, individual metafields such as `sparklayer.pack_size` are ignored. See [Which rule wins](https://docs.sparklayer.io/help/storefront/product-settings.md#which-rule-wins).

## Examples

These are the common rules. Build your own with the [form](#set-up-variant-visibility), or copy one into the variant's `sparklayer.settings` metafield and change the group name.

### Hide a product from all B2B customers except one group

This variant is hidden from all B2B customers except those in the `vip` customer group (customers tagged `b2b-vip`):

```json
[
  {
    "customer_group": "base",
    "display": false
  },
  {
    "customer_group": "vip",
    "display": true
  }
]
```

### Hide a product from one customer group

This variant stays visible to all B2B customers except those in the `vip` customer group:

```json
[
  {
    "customer_group": "vip",
    "display": false
  }
]
```

## FAQs

**How many variants can a product have?**

We can only guarantee that variants are shown and hidden as expected on products with 250 variants or fewer, because of the way Shopify gives themes access to product variants. See [B2B Catalogs limitations](https://docs.sparklayer.io/help/storefront/b2b-catalogs/limitations.md).


---

# Customise the access denied page

URL: https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-access-denied-view
Applies to: Shopify

Change the access denied page customers see when they open a product hidden from them, by editing the B2B Catalogs Liquid snippet in your Shopify theme.

> **Quick summary**
>
> - When a customer opens the product page of a product that's hidden from them, they see an "access denied" view instead.
> - You (or your developer) can change its content by editing `snippets/sparklayer-b2b-catalogs-access-denied.liquid` in your theme. B2B Catalogs adds this file automatically.
> - If you disable B2B Catalogs on the theme, your changes to the file are removed.

## Edit the access denied page

The access denied page is a file in your theme's code, so changing it is a small code edit. If you don't edit your theme yourself, ask your developer or agency.

1. In your Shopify admin, go to **Online Store > Themes** ([open in the Shopify admin](https://admin.shopify.com/themes)).
2. On the theme, open the **…** menu and click **Edit code**.
3. Open `snippets/sparklayer-b2b-catalogs-access-denied.liquid`, make your changes and click **Save**.

**More detail**

Disabling B2B Catalogs on a theme removes your changes to this file. Keep a copy of your changes before you disable the app, so you can add them back later. See [Enable or disable it on other themes](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md#enable-or-disable-it-on-other-themes).

## Next steps

- [Show or hide products](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-your-catalogs.md): Choose which products B2B and retail customers see
- [B2B Catalogs FAQs](https://docs.sparklayer.io/help/storefront/b2b-catalogs/faqs.md): Answers to common questions about hiding products and pages


---

# B2B Catalogs limitations

URL: https://docs.sparklayer.io/help/storefront/b2b-catalogs/limitations
Applies to: Shopify

B2B Catalogs limitations: variants and retail shoppers, grid and filter counts, the 250-variant limit, carts, permalinks, third-party apps and Liquid errors.

> **Quick summary**
>
> - B2B Catalogs hides products and variants in your Shopify theme, so a few Shopify behaviours can work around it. Check these before you rely on it to restrict access.
> - Variant rules for customer groups only apply to B2B customers, and are only guaranteed on products with 250 variants or fewer. Retail shoppers see every variant.
> - A customer can still buy a hidden product if it's already in their cart, or if they add it with an add-to-cart permalink.

## Limits at a glance

| Limitation | What happens |
| --- | --- |
| [Variants and retail shoppers](#variants-and-retail-shoppers) | Variant rules don't hide anything from retail shoppers, and Shopify can't hide a single variant from them. |
| [Variant count](#advanced-catalogs-variant-count) | Hiding and showing variants is only guaranteed on products with 250 variants or fewer. |
| [Collection grids, search and filter counts](#grids-search-and-filter-counts) | A hidden product can still take a place in a grid and count towards totals. |
| [Products already in a cart](#hidden-product-add-to-cart-caveats) | The product stays in the cart and the customer can check out. |
| [Add-to-cart permalinks](#hidden-product-add-to-cart-caveats) | Customers can still add a hidden product to their cart with a permalink. |
| [Third-party apps](#third-party-app-compatibility) | We can't guarantee compatibility with every app. |
| [Invalid Liquid syntax](#invalid-liquid-syntax) | B2B Catalogs can't change theme files that contain errors in their code (Liquid). |

## Variants and retail shoppers

Variant rules in the `sparklayer.settings` metafield only apply to signed-in B2B customers, by [customer group](https://docs.sparklayer.io/help/glossary.md#customer-group). They don't hide anything from retail shoppers or signed-out visitors, who see every variant your theme shows. Shopify can't hide a single variant of a product from them either: `b2b-only` and `b2c-only` tags work on whole products.

To sell a variant to B2B customers only, such as a 12-pack case of a bottle you also sell singly, make it a separate product and tag it `b2b-only`. [Sell a B2B-only version of a product](https://docs.sparklayer.io/help/guides/sell-b2b-only-versions.md) takes you through it. For a worked example of ranges per customer group, see [Example: a product range for each customer group](https://docs.sparklayer.io/help/storefront/product-settings.md#example-a-product-range-for-each-customer-group).

## Collection grids, search and filter counts

B2B Catalogs hides products in your theme as each page loads, rather than removing them from Shopify's collection and search results. So:

- **A collection page can show gaps or fewer products per page.** A hidden product still takes its place in the grid, so a page of 24 can show fewer than 24.
- **Product counts and filter counts can include hidden products.** For example, "36 products" or a filter showing (12) can count products the customer can't see.

If counts matter, such as on a B2B-only store, keep B2B-only and retail products in separate collections.

## Products with more than 250 variants

[Catalogs per customer group](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-advanced-catalogs.md) only reliably hide and show variants on products with 250 variants or fewer. This is because of the way Shopify gives themes access to product variants.

## Hidden products in a cart

Hiding a product doesn't remove it from carts. If a product is already in a customer's cart before you hide it from them, it stays there and they can check out with it.

Customers can also still add a hidden product to their cart with an add-to-cart permalink (a link that adds a product to the cart directly).

## Third-party apps

There are a great many Shopify apps, so we can't guarantee B2B Catalogs works with every third-party app.

## Invalid Liquid syntax

B2B Catalogs can't change theme files that contain invalid Liquid syntax. Liquid is the code Shopify themes are written in, so this usually means a mistake in a recent edit to your theme's code.

If you see the error `invalid liquid syntax in file <file>` when you enable or disable B2B Catalogs on a theme, fix the syntax in the file it names, then try again.


---

# B2B Catalogs FAQs

URL: https://docs.sparklayer.io/help/storefront/b2b-catalogs/faqs
Applies to: Shopify

Answers on B2B Catalogs pricing, setup, SEO and sitemaps, customer group and variant-level visibility, disabling on a theme, getting help and uninstalling.

## Setup and pricing

**Is B2B Catalogs free?**

Yes. B2B Catalogs is a free standalone Shopify app, included with every SparkLayer plan, including the free plan. Install it from the [Shopify App Store](https://apps.shopify.com/sparklayer-b2b-catalogs). See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).

**Do I need a developer to set it up?**

No. Your merchandising team can manage everything. Tag a product and save it, and the change goes live straight away. There are no manual theme edits, no custom code and no waiting for a release. To get started, see [Install and enable B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md#install-and-enable-b2b-catalogs).

## Visibility

**Where exactly are hidden products hidden?**

On product pages, collection pages and in store search results. If a customer opens a hidden product's URL directly, they see an "access denied" page, which you can [customise](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-access-denied-view.md). A hidden product can still take a place in a collection grid and count towards product and filter totals: see [Collection grids, search and filter counts](https://docs.sparklayer.io/help/storefront/b2b-catalogs/limitations.md#grids-search-and-filter-counts).

For how this compares with hiding a product with the `sparklayer.settings` metafield alone, see [What hides what](https://docs.sparklayer.io/help/storefront/product-settings.md#what-hides-what).

**Will hidden products still appear in my sitemap or affect SEO?**

Products tagged `b2b-only` still appear in the sitemap that Shopify generates automatically. The product pages themselves aren't visible to search engines, so they won't show up in external search results.

To remove these products from your sitemap completely, follow [Shopify's guidance on hiding products from search engines](https://help.shopify.com/en/manual/promoting-marketing/seo/hide-a-page-from-search-engines#custom-metafield). This may also stop those products appearing in your store's own search results.

**Can I show different products to different B2B customer groups?**

Yes, with the [SparkLayer Wholesale app](https://docs.sparklayer.io/help/platforms/shopify/install.md) as well. The `sparklayer.settings` variant metafield shows or hides products for each customer group.

For example, you could hide a product from all B2B customers except your VIP group. Or you could hide a range from one group while keeping it visible to everyone else. See the worked example in [A product range for each customer group](https://docs.sparklayer.io/help/storefront/product-settings.md#example-a-product-range-for-each-customer-group).

See [Catalogs per customer group](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-advanced-catalogs.md) for how the rules work, and [Hide products from customers](https://docs.sparklayer.io/help/guides/hide-products.md) for a form that writes them.

**Can I control visibility at the variant level?**

For B2B customer groups, yes, with the [SparkLayer Wholesale app](https://docs.sparklayer.io/help/platforms/shopify/install.md) as well. For example, your wholesale group could see a 12-pack case that your VIP group doesn't. See [Catalogs per customer group](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-advanced-catalogs.md).

Not for retail (B2C) customers: variant rules don't hide anything from them, and Shopify can't hide a single variant of a product. To sell the 12-pack case to B2B customers only, make it a separate product and tag it `b2b-only`: see [Sell a B2B-only version of a product](https://docs.sparklayer.io/help/guides/sell-b2b-only-versions.md). See [Variants and retail shoppers](https://docs.sparklayer.io/help/storefront/b2b-catalogs/limitations.md#variants-and-retail-shoppers).

## Disabling and uninstalling

**What happens if I disable B2B Catalogs on a theme?**

The visibility rules are removed from that theme. If you've customised `snippets/sparklayer-b2b-catalogs-access-denied.liquid`, your changes are removed too, so keep a copy of them before you disable it.

**How do I uninstall B2B Catalogs?**

First disable it on every theme where it's enabled: open the app in your Shopify admin and click **Disable** on each enabled theme. Then uninstall the app.

If you've already uninstalled it without disabling it first, reinstall it temporarily, disable it on your themes, then uninstall it again.

See [Uninstall B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs/removing-b2b-catalogs.md).

## Getting help

**How do I contact support about B2B Catalogs?**

Our support team can help you set up and troubleshoot B2B Catalogs on your store. Email [support@sparklayer.io](mailto:support@sparklayer.io), or click the message icon (a purple speech bubble) in the B2B Catalogs app or at the bottom right of this page.

So we can help quickly, tell us what your query is about and include any screenshots that show the problem.

**How quickly will you reply?**

We aim to reply to every query within 24 hours, but allow up to 2 working days. The message icon isn't a live chat that's always staffed, so you won't always get a reply in real time. See [Contact support](https://docs.sparklayer.io/help/support.md) for when our team is available.


---

# Uninstall B2B Catalogs

URL: https://docs.sparklayer.io/help/storefront/b2b-catalogs/removing-b2b-catalogs
Applies to: Shopify

Uninstall B2B Catalogs safely: disable it on every Shopify theme where it's enabled first, and what to do if you removed the app before disabling it.

> **Quick summary**
>
> - Before you uninstall B2B Catalogs, you must disable it on every theme it's enabled on. Disabling removes the app's changes from each theme, but uninstalling doesn't.
> - You disable it in the app in your Shopify admin, one theme at a time.
> - If you've already uninstalled the app, reinstall it temporarily, disable it on your themes, then uninstall it again.

## Uninstall the app

Disable the app on each theme first, then uninstall it:

1. Open B2B Catalogs in your Shopify admin.
2. Under **Enable on your theme**, click **Disable** on every theme whose **Status** is **Enabled**.
3. When every theme shows **Disabled**, uninstall the B2B Catalogs app.

**More detail**

Disabling the app on a theme also removes any changes you've made to the [access denied page](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-access-denied-view.md), so keep a copy first if you want them.

## If you've already uninstalled it

Reinstall the app so you can disable it on your themes:

1. Reinstall [B2B Catalogs](https://apps.shopify.com/sparklayer-b2b-catalogs) from the Shopify App Store.
2. Follow the steps in [Uninstall the app](#uninstall-the-app).

## Next steps

- [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md): What the app does and how to enable it on a theme again
- [Cancel, uninstall or transfer SparkLayer](https://docs.sparklayer.io/help/platforms/shopify/uninstall.md): Remove the main SparkLayer app from your Shopify store


---

# Storefront options

URL: https://docs.sparklayer.io/help/storefront/storefront-options

Change SparkLayer's storefront without code: checkout, My Account, pricing display, text overrides, custom slots and analytics, then save and publish.

> **Quick summary**
>
> - **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app is where you change what B2B customers see and can do on your store, without editing code in your theme.
> - It has 6 sections: **Checkout**, **My Account**, **Pricing and display**, **Translation overrides**, **Custom slots** and **Analytics**.
> - Nothing reaches your store until you click **Save and publish**. Buyers see the changes on their next page load.
> - Settings your developer already made in the [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting) (the SparkLayer code in your theme) keep working. **Import snippet** and **Copy snippet** move settings between the two.

## How it works

Storefront options are settings that used to need code in the Core Script. On the Options page, you change them on screen and publish them in one step. Only signed-in B2B customers see the result.

From change to live store:

1. **Change settings**: Open a section of the Options page and change what you need
2. **Save and publish**: One button saves your changes and makes them live
3. **Buyers see it**: Signed-in B2B customers see the change on their next page load

The **Publishing** card at the top of the page shows the status:

| Status | What it means |
| --- | --- |
| **Published** | Your storefront uses these options. Changes go live when you publish. |
| **Not published** | Nothing has been published yet, so buyers see SparkLayer's defaults. |

As a rule, **Settings > Configurations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations** in the Shopify app turns features on and off, and the Options page sets how they look and behave on your storefront.

A few settings are on both screens, and carry an **Also in Configurations** badge here. They're the same setting in 2 places: change it on either screen and the other one follows.

| On the Options page | At **Settings > Configurations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations** in the Shopify app |
| --- | --- |
| **Checkout** > **Hide AI features in the cart** | **Pricing and cart** > **Hide AI features in the cart** |
| **My Account** > **Show payment status** | **Ordering** > **Payments visibility** |
| **My Account** > **Timeline and communications** | **Quotes and invoices** > **Timeline and communications** |
| **Pricing and display** > **Tiered pricing across variants** | **Pricing and cart** > **Tiered pricing across variants** |

## Change a setting and publish it

Every change follows the same 3 steps:

1. Go to **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app.
2. Click a section to open it, and change the settings you need. See the [settings reference](#settings-reference).
3. Click **Save and publish**.

There's no separate draft: saving and publishing is one step.

## Copy or import your options as a snippet

Every option on this page is also a Core Script setting, in the `window.sparkOptions` code your developer uses. Use these buttons to move settings between the two, for example to back up your settings or hand them to a developer:

| Button | What it does |
| --- | --- |
| **Copy snippet** | Copies your options as a `window.sparkOptions` snippet. Use it to keep a copy before a big change, or to send your settings to a developer. |
| **Import snippet** | Loads the values from a `window.sparkOptions` snippet you paste into the page. Click **Save and publish** to make them live. |

## Add a Core Script setting

Some pages show code labelled **Core Script**. Each is a setting for the Core Script, the SparkLayer code in your theme, and is usually a job for your developer.

1. Open your theme's code. On Shopify, that's `theme.liquid`.
2. Find the `window.sparkOptions` block, just before the closing `</head>` tag. If there isn't one, add it.
3. Paste the setting inside the curly brackets, after any settings already there, and end it with a comma.
4. Save, and check the change on your store while signed in as a B2B customer.

For example, with two settings:

```html title="theme.liquid"
<script>
  window.sparkOptions = {
    language: "en",
    display: {
      hideFinancials: true,
    },
  };
</script>
```

If you already have a setting, such as `translations` or `display`, add the new lines inside it rather than adding it twice. For more, see [Modifying the Core Script](https://docs.sparklayer.io/developers/frontend.md#modifying-the-core-script) in the developer docs.

## Settings reference

The Options page has 6 sections. Click one to open it. Switches marked "(on)" below are on by default.

### Checkout

What buyers fill in and choose at checkout: fields, payment methods and cart behaviour.

| Setting | What it does |
| --- | --- |
| **Checkout fields** | The extra fields customers fill in at checkout, such as a PO number or delivery notes. Click **Add field** to add one. See [Checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md). |
| **Payment methods, in order** | Drag **Payment on account**, **Payment by invoice**, **Upfront payment** and **Quote** to set the order buyers see them in at checkout. Which methods each customer can use is set by their customer group, where the names differ: see [The same method in each place](https://docs.sparklayer.io/help/ordering/payment-methods.md#names). |
| **Save addresses to the address book** (on) | A new address entered at checkout is saved to the buyer's address book by default. |
| **Hide AI features in the cart** | Hides the [Intelligent Cart](https://docs.sparklayer.io/help/ordering/intelligent-cart.md) features in the SparkLayer cart. Also in Configurations. |

Standard checkout fields need Core Script version 4.7.0 or later. Custom fields work on any version. Check your version 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.

### My Account

What buyers see and do in their [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) area.

| Setting | What it does |
| --- | --- |
| **Hide financial figures** | Hides financial figures from buyers. It also hides the **Financials** section of My Account. |
| **Show shipping address in the order list** | Shows each order's shipping address beside it in the order list. |
| **Show payment status** | Shows the payment status of orders in My Account. Also in Configurations, where it's called **Payments visibility**. |
| **Timeline and communications** | Buyers and sales agents can send messages on quotes and orders. Also in Configurations. See [Order timeline and messages](https://docs.sparklayer.io/help/customers/timeline.md). |
| **Favourites lists** (on) | Buyers can save products to a favourites list. See [Favourites](https://docs.sparklayer.io/help/ordering/favourites.md). |
| **Shopping lists** (on) | Buyers can save reusable shopping lists. See [Shopping lists](https://docs.sparklayer.io/help/ordering/shopping-lists.md). |
| **Account sections, in order** | Drag the sections to set the order they appear in: **Recent activity**, **Favourites**, **Shopping lists**, **Financials**, **My details**, **Reports**, **Address book** and **Company users**. Each one shows whether buyers can see it. |

### Pricing and display

How buyers see prices, savings and the product interfaces.

| Setting | What it does |
| --- | --- |
| **Base savings on RRP** | Shows savings against the RRP, rather than the buyer's own price. |
| **RRP toggle** | Buyers can switch between seeing the RRP and their own prices. See [How prices are shown](https://docs.sparklayer.io/help/pricing/pricing-display.md). |
| **Savings on price breaks** (on) | Shows the amount saved next to each quantity price break. |
| **Round price break percentages** (on) | Shows price break percentages as whole numbers. |
| **Tiered pricing across variants** (on) | Quantity tiers count every variant of a product together. Also in Configurations. See [Quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md). |
| **Dark theme** | Shows SparkLayer's interfaces in the dark colour scheme, for stores with a dark theme. See [dark mode](https://docs.sparklayer.io/help/storefront/customising-design.md#turn-on-dark-mode). |

### Translation overrides

Translation overrides change the text buyers see in SparkLayer, such as a button label or a heading, for each language. Each piece of text has a name, called a key, such as `cart.checkout.notes.label` for the label of the order notes field.

Until you add one, the section shows "No overrides. SparkLayer's own text is used."

1. Click **Add override**, choose the language and the key, and enter your own text.
2. Click **Save and publish**.

Translation overrides replace the `translations` setting in the Core Script. See [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md#change-sparklayers-text) for how to find a key, the supported languages and the keys with variables.

### Custom slots

Custom slots let you show buyers your own content in set places in SparkLayer's interfaces, such as a message in the cart. Click **Add slot** to add one. These are the slots you can use:

| Slot | Slot ID |
| --- | --- |
| My Account | `spark-slot-my-account` |
| My Cart | `spark-slot-my-cart` |
| Cart line item | `spark-slot-my-cart-line-item` |
| Order complete | `spark-slot-order-complete` |
| Cart shipping step | `spark-slot-cart-shipping-step` |
| Cart payment step | `spark-slot-cart-payment-step` |
| Purchase summary header | `spark-slot-purchase-summary-header` |
| Purchase summary footer | `spark-slot-purchase-summary-footer` |

To add your content to these places, see [Custom slots (targets)](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md).

### Analytics

Analytics sends SparkLayer storefront events, such as items added to the cart, to your analytics tools. Click **Add provider** to connect one.

## FAQs

**Do I still need to edit my theme code to configure SparkLayer?**

No. Settings that used to need Core Script changes can be managed on the Options page. Design changes, such as your brand colours, still use CSS: see [Customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md).

**Does this replace my existing Core Script?**

No. The Options page works alongside your Core Script, so anything already set there keeps working. To bring settings from your theme code onto this page, use **Import snippet**.

**Will my changes go live as soon as I make them?**

Only when you click **Save and publish**. Buyers then see them on their next page load.

**Can I undo a change after publishing?**

There's no undo button. Change the setting back and click **Save and publish** again. Before a big change, click **Copy snippet** to keep a copy of your settings: you can bring them back with **Import snippet**.

**Why does a setting say Also in Configurations?**

It's the same setting as one at **Settings > Configurations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations** in the Shopify app. Changing it on either screen changes it on both.


---

# Customising the design

URL: https://docs.sparklayer.io/help/storefront/customising-design

Match SparkLayer's storefront to your brand by changing 4 lines of CSS for colours and fonts, turn on dark mode, and fine-tune elements with CSS variables.

> **Quick summary**
>
> - Your B2B customers see SparkLayer's [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) in your brand colours and fonts. These come from a short piece of CSS (styling code) that you add to your store's theme.
> - There are no colour or font settings in SparkLayer. The only design setting without code is **Dark theme**, under **Pricing and display** at **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app.
> - For most stores, 4 values are enough: a brand colour, a hover colour, a body font and a heading font. See [Change your brand colours and fonts](#add-custom-css-to-your-store).
> - If someone else edits your theme, send them this page. The [CSS variable reference](#variable-reference) is for your developer or agency. Design customisation is included on every plan. Some things, such as the product page layout, button order and button width, have no variable: see [What you can and can't change](https://docs.sparklayer.io/help/storefront/what-you-can-change.md).

## How it works

SparkLayer's interfaces start with neutral styling. Each colour, font and size in them has a named setting, called a CSS variable, such as `--b2b-brand-color`. When you set a variable in your theme, your value replaces SparkLayer's default everywhere that variable is used.

You don't need to know CSS to change your brand colours and fonts. You copy a ready-made block of code, change 4 values and paste it into your theme.

## Change your brand colours and fonts

1. Copy the [recommended starting CSS](#recommended-starting-css) below.
2. Change the 4 brand values at the top of it to your own (see [the 4 brand values](#the-four-brand-values)). Leave the rest as it is.
3. Paste the code into your theme's `<head>`, after the SparkLayer Core Script if your theme has it (see [where to paste the code](#where-to-paste-the-code)).
4. Save your theme, then sign in to your store as a B2B customer to check the result.

**More detail**

The starting code lives on this page, not in SparkLayer: there's no custom CSS screen. **Design and tips** at **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app links here. The interfaces only appear for signed-in B2B customers, so you won't see your changes while signed out. For more on making code changes to your store, see the [frontend integration guide](https://docs.sparklayer.io/developers/frontend.md).

### The 4 brand values

| Value | What to enter | Example |
| --- | --- | --- |
| `--b2b-brand-color` | Your main brand colour, as a hex code. It's used for buttons, links and highlights. | `#1A4D8F` |
| `--b2b-brand-color-hover` | The colour buttons change to when a customer points at them, usually a slightly darker shade of your brand colour. | `#133A6B` |
| `--b2b-brand-font` | The font for body text. List your font first, then a fallback. | `Arial, sans-serif` |
| `--b2b-brand-font-heading` | The font for headings and buttons. | `Georgia, serif` |

A hex code is the 6-character code for a colour, starting with `#`. Your brand guidelines or your theme's colour settings usually show it. Keep the semicolon (`;`) at the end of each line.

**Every CSS variable starts with two hyphens**, for example `--spark-primary-color` or `--b2b-brand-color`. A variable with one hyphen, or with the hyphens turned into a dash when you copied it, is ignored.

### Where to paste the code

**Shopify:**

1. In your Shopify admin, go to **Online Store > Themes** ([open in the Shopify admin](https://admin.shopify.com/themes)).
2. On your current theme, open the **…** menu and click **Edit code**.
3. Open `layout/theme.liquid`, paste the code just before the closing `</head>` tag and click **Save**.

Your developer can put it in a separate CSS file in your theme instead.

**Other platforms:**

Add the code to the header template of your site, alongside the SparkLayer Core Script. Your platform's install guide shows where: [BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce/install.md), [Wix](https://docs.sparklayer.io/help/platforms/wix/install.md), [WooCommerce](https://docs.sparklayer.io/help/platforms/woocommerce/install.md) or [Magento](https://docs.sparklayer.io/help/platforms/magento/install.md).

## Recommended starting CSS

This sample sets your brand colours and fonts and applies them throughout SparkLayer. Change the 4 values under "Set the brand styling" first. The rest are optional fine-tuning.

```html title="Sample CSS Code"
<!-- SparkLayer Sample CSS Code -->

<style type="text/css">

:root {
  /* Set the brand styling */
  --b2b-brand-color: #000; /* Main brand colour */
  --b2b-brand-color-hover: #333; /* Main brand colour hover */
  --b2b-brand-font: Arial, sans-serif; /* Main brand font */
  --b2b-brand-font-heading: Arial, sans-serif; /* Main brand heading font */

  /* Update colours */
  --spark-default-body-color: #555555; /* Main body colour */
  --spark-primary-color: #000000; /* Main title colour */
  --spark-secondary-color: var(--b2b-brand-color); /* Main highlight colour */
  --spark-link-color: var(--b2b-brand-color); /* Link colour */

  /* Typefaces */
  --spark-font-default: var(--b2b-brand-font); /* Body typeface */
  --spark-font-highlight: var(--b2b-brand-font-heading); /* Highlight typeface */
  --spark-font-weight-default: 400; /* Default font weight */
  --spark-font-weight-medium: 500; /* Medium font weight */
  --spark-font-weight-heavy: 600; /* Bold font weight */

  /* General */
  --spark-border-radius-default: 0; /* Default border radius */
  --spark-drawer-max-width: 700px; /* Width of overlay */
  --spark-drawer-max-width-wide: 1000px; /* Width of overlay in maximised view */

  /* Font sizes */
  --spark-font-default-size: 14px; /* Default font size*/
  --spark-font-default-size-small: 14px; /* Default font size - small screens */
  --spark-header-font: var(--b2b-brand-font-heading); /* Header typeface */
  --spark-header-font-weight: 500; /* Header font weight */
  --spark-h1-fontsize: 24px; /* Header 1 font size */
  --spark-h2-fontsize: 22px; /* Header 2 font size */
  --spark-h3-fontsize: 20px; /* Header 3 font size */
  --spark-h4-fontsize: 16px; /* Header 4 font size */
  --spark-h5-fontsize: 15px; /* Header 5 font size */
  --spark-h6-fontsize: 14px; /* Header 6 font size */

  --spark-pricing-fontsize: 20px; /* Font size of pricing */
  --spark-pricing-font-weight: 500; /* Font weight of pricing */
  --spark-pricing-fontsize-small: 14px; /* Font size of pricing on mobile */

  --spark-product-code-fontsize: 16px; /* Font size of product code */
  --spark-product-code-font-weight: 500; /* Font weight of product code */
  --spark-product-code-fontsize-small: 14px; /* Font size of product code on mobile */
  --spark-product-stockstatus-align: flex-start; /* Alignment of stock status for single variants */

  /* Buttons */
  --spark-button-font-family: var(--b2b-brand-font-heading); /* Button typeface */
  --spark-button-color: var(--b2b-brand-color); /* Default button colour */
  --spark-button-color-highlight: var(--b2b-brand-color-hover); /* Default button colour hover */
  --spark-button-large-color: var(--b2b-brand-color); /* Large button colour */
  --spark-button-large-color-highlight: var(--b2b-brand-color-hover); /* Large button colour hover */
  --spark-border-radius-button: 0; /* Button border radius */
  --spark-button-font-weight: 600; /* Button font weight */
  --spark-button-text-transform: none; /* Button text transform */
  --spark-button-text-letter-spacing: 0; /* Button letter spacing */
  --spark-button-padding: 1em 2.75em; /* Button padding */
  --spark-button-small-font-size: 16px; /* Small button font size */

  /* Tables */
  --spark-table-border-color: #CCCCCC; /* Table border colour */
  --spark-table-header-background-color: #F1F1F1; /* Table header background */
  --spark-table-header-text-color: #222222; /* Table header font colour */
  --spark-table-header-font-weight: 500; /* Table header font weight */

  /* Product Card */
  --spark-product-card-button-radius: 0; /* Button radius */
  --spark-product-card-button-padding: 0.75em 1em; /* Button padding */
  --spark-product-card-pricing-font-size: 15px; /* Pricing font size */
  --spark-product-card-pricing-font-size-small: 14px; /* Pricing font size on mobile */
  --spark-product-card-select-min-height: 0; /* Set a min-height for select menu */
}
</style>

<!-- End SparkLayer Sample CSS Code -->
```

## Turn on dark mode

With dark mode, customers see SparkLayer's interfaces with light text on dark backgrounds. Turn it on if your store uses a dark theme. You don't need code:

1. Go to **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app.
2. Open **Pricing and display** and turn on **Dark theme**.
3. Click **Save and publish**. See [Storefront options](https://docs.sparklayer.io/help/storefront/storefront-options.md).

**Turn on dark mode in the Core Script (for developers)**

Instead of the toggle, your developer can add `darkTheme: true` to the `display` settings of your [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting):

```javascript title="Core Script"
display: {
  darkTheme: true,
},
```

You can fine-tune dark mode's colours with the [dark mode variables](#dark-mode-variables).

## Add your own content with custom slots

Custom slots (also called targets) let you show customers your own content, such as a message or a banner, in set places in the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md). See [Custom slots (targets)](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md).

## Find the variable for an element

This section and the reference below are for your developer or agency. To change one element, such as a table header, find the CSS variable it uses:

1. On your store, signed in as a B2B customer, right-click the element you want to change and choose **Inspect** to open your browser's developer tools.
2. In the **Styles** panel, look for values written as `var(--spark-…)`. For example, a table header's text colour shows as `color: var(--spark-table-header-text-color, #555)`.
3. Set that variable in your custom CSS. The second value in brackets is the default.

## CSS variable reference (for developers)

Each table lists the CSS variables for one area of SparkLayer's interfaces, what they change and their default value. Copy the sample code for an area to see every variable together.

### Colours

```html title="Sample CSS Code"
<style>
:root {
    /* Colours */
    --spark-default-body-color: #555555;
    --spark-primary-color: #000000;
    --spark-primary-color-light: #F5F5F5;
    --spark-primary-color-dark: #999999;
    --spark-secondary-color: #125EF8;
    --spark-tertiary-color: #00AF76;
    --spark-lightest-color: #FFFFFF;
    --spark-success-color: #00AF76;
    --spark-error-color: #EF0000;
    --spark-warn-color: #FF9243;
    --spark-link-color: #125EF8;
    --spark-input-color: #CCCCCC;
}
</style>
```

| Variable | What it changes | Default |
| --- | --- | --- |
| `--spark-default-body-color` | Body text colour | `#555555` |
| `--spark-primary-color` | Title text colour, for example price information | `#000000` |
| `--spark-primary-color-light` | Light shading, for example table shading | `#F5F5F5` |
| `--spark-primary-color-dark` | Dark shading | `#999999` |
| `--spark-secondary-color` | Secondary colour, for example a highlight colour | `#125EF8` |
| `--spark-tertiary-color` | Tertiary colour, for example the large button colour | `#00AF76` |
| `--spark-lightest-color` | Lightest colour, for example white | `#FFFFFF` |
| `--spark-success-color` | Success message colour | `#00AF76` |
| `--spark-error-color` | Error message colour | `#EF0000` |
| `--spark-warn-color` | Warning message colour | `#EDC35C` |
| `--spark-link-color` | Link colour | `#125EF8` |
| `--spark-input-color` | Form field border colour | `#CCCCCC` |

### Typography

SparkLayer uses 2 typefaces by default: [Roboto](https://fonts.google.com/specimen/Roboto) for body text and [Poppins](https://fonts.google.com/specimen/Poppins) for highlights. You can replace them with the variables below.

If you use custom fonts (for example from Google Fonts), include them in your website's main CSS file, and in your site header if needed. They then load before SparkLayer uses them.

```html title="Sample CSS Code"
<style>
:root {
    /* Typography */
    --spark-font-default: 'Roboto', sans-serif;
    --spark-font-highlight: 'Poppins', sans-serif;
    --spark-font-weight-default: 400;
    --spark-font-weight-light: 300;
    --spark-font-weight-medium: 500;
    --spark-font-weight-heavy: 600;
    --spark-header-font: 'Poppins', sans-serif;
    --spark-header-font-weight: 500;
    --spark-header-text-transform: none;
    --spark-header-letter-spacing: 0em;
    --spark-h1-fontsize: 24px;
    --spark-h2-fontsize: 22px;
    --spark-h3-fontsize: 20px;
    --spark-h4-fontsize: 16px;
    --spark-h5-fontsize: 15px;
    --spark-h6-fontsize: 14px;
    --spark-pricing-fontsize: 16px;
    --spark-pricing-font-weight: 400;
    --spark-pricing-fontsize-small: 14px;
    --spark-packsize-fontsize: 16px;
    --spark-packsize-font-weight: 400;
    --spark-packsize-fontsize-small: 14px;
    --spark-product-code-fontsize: 16px;
    --spark-product-code-font-weight: 400;
    --spark-product-code-fontsize-small: 14px;
    --spark-product-stockstatus-fontsize: 16px;
    --spark-product-stockstatus-fontsize-small: 14px;
    --spark-product-stockstatus-align: flex-start;
    --spark-product-stockstatus-back-order-display: flex;
}
</style>
```

| Variable | What it changes | Default |
| --- | --- | --- |
| `--spark-font-default` | Main body font | `'Roboto', sans-serif` |
| `--spark-font-highlight` | Highlight font | `'Poppins', sans-serif` |
| `--spark-font-weight-default` | Default font weight | `400` |
| `--spark-font-weight-light` | Light font weight | `300` |
| `--spark-font-weight-medium` | Medium font weight | `500` |
| `--spark-font-weight-heavy` | Heavy font weight | `600` |
| `--spark-header-font` | Heading font | `'Poppins', sans-serif` |
| `--spark-header-font-weight` | Heading font weight | `500` |
| `--spark-header-text-transform` | Heading text transform | `none` |
| `--spark-header-letter-spacing` | Heading letter spacing | `0em` |
| `--spark-h1-fontsize` | H1 font size | `24px` |
| `--spark-h2-fontsize` | H2 font size | `22px` |
| `--spark-h3-fontsize` | H3 font size | `20px` |
| `--spark-h4-fontsize` | H4 font size | `16px` |
| `--spark-h5-fontsize` | H5 font size | `15px` |
| `--spark-h6-fontsize` | H6 font size | `14px` |
| `--spark-pricing-fontsize` | Price font size | `16px` |
| `--spark-pricing-font-weight` | Price font weight | `500` |
| `--spark-pricing-fontsize-small` | Price font size on mobile | `14px` |
| `--spark-packsize-fontsize` | Pack size font size | `16px` |
| `--spark-packsize-font-weight` | Pack size font weight | `400` |
| `--spark-packsize-fontsize-small` | Pack size font size on mobile | `14px` |
| `--spark-product-code-fontsize` | Product code font size | `16px` |
| `--spark-product-code-font-weight` | Product code font weight | `500` |
| `--spark-product-code-fontsize-small` | Product code font size on mobile | `14px` |
| `--spark-product-stockstatus-align` | Alignment of the stock status message | `flex-start` |
| `--spark-product-stockstatus-back-order-display` | Display of the pre-order message | `flex` |

### General

```html title="Sample CSS Code"
<style>
:root {
    /* General */
    --spark-border-radius-default: 4px;
    --spark-border-radius-large: 8px;
    --spark-drawer-max-width: 700px;
    --spark-drawer-max-width-wide: 1000px;
    --spark-loading-background-color: #DEDEDE;
    --spark-loading-background-overlay-product: 255, 255, 255;
    --spark-container-content-top: 3em;
    --spark-container-content-bottom: 3em;
    --spark-container-content-side: 4.5em;
    --spark-container-content-reduced: 1.5em;
    --spark-spinner-default-color: #125EF8;
}
</style>
```

| Variable | What it changes | Default |
| --- | --- | --- |
| `--spark-border-radius-default` | Default border radius | `4px` |
| `--spark-border-radius-large` | Overlay border radius | `8px` |
| `--spark-drawer-max-width` | Width of the overlay | `700px` |
| `--spark-drawer-max-width-wide` | Width of the overlay in maximised view | `1000px` |
| `--spark-loading-background-color` | Loading skeleton colour | `#DEDEDE` |
| `--spark-loading-background-overlay-product` | Loading overlay colour on product pages | `255,255,255` |
| `--spark-container-content-top` | Overlay spacing: top | `3em` |
| `--spark-container-content-bottom` | Overlay spacing: bottom | `3em` |
| `--spark-container-content-side` | Overlay spacing: sides | `4.5em` |
| `--spark-container-content-reduced` | Overlay spacing: reduced | `1.5em` |
| `--spark-spinner-default-color` | Loading spinner colour | `#125EF8` |

### Buttons

```html title="Sample CSS Code"
<style>
:root {
    /* Buttons */
    --spark-button-font-family: 'Poppins', sans-serif;
    --spark-button-border: 0;
    --spark-button-font-size: 15px;
    --spark-button-font-weight: 400;
    --spark-button-padding: 0.875em 1.75em;
    --spark-button-radius: 4px;
    --spark-button-text-transform: none;
    --spark-button-text-letter-spacing: 0;
    --spark-button-raised-background: #125EF8;
    --spark-button-raised-background-hover: #508AFF;
    --spark-button-raised-color: #FFFFFF;
}
</style>
```

| Variable | What it changes | Default |
| --- | --- | --- |
| `--spark-button-font-family` | Button font | `'Poppins', sans-serif` |
| `--spark-button-border` | Button border | `0` |
| `--spark-button-font-size` | Button font size | `15px` |
| `--spark-button-font-weight` | Button font weight | `400` |
| `--spark-button-padding` | Button padding | `0.875em 1.75em` |
| `--spark-button-radius` | Button border radius | `4px` |
| `--spark-button-text-transform` | Button text transform | `none` |
| `--spark-button-text-letter-spacing` | Button letter spacing | `0` |
| `--spark-button-raised-background` | Button background | `#125EF8` |
| `--spark-button-raised-background-hover` | Button background on hover | `#508AFF` |
| `--spark-button-raised-color` | Button text colour | `#FFFFFF` |

#### Disabled buttons

```html title="Sample CSS Code"
<style>
:root {
   /* Disabled buttons */
   --spark-button-disabled-background: #DFDFDF;
   --spark-button-disabled-color: #9F9F9F;
}
</style>
```

| Variable | What it changes | Default |
| --- | --- | --- |
| `--spark-button-disabled-background` | Disabled button background | `#DFDFDF` |
| `--spark-button-disabled-color` | Disabled button text colour | `#9F9F9F` |

#### Large buttons

```html title="Sample CSS Code"
<style>
:root {
    /* Large buttons */
    --spark-button-large-font-size: 18px;
    --spark-button-large-padding: 0.875em 1.75em;
    --spark-button-large-background: #125EF8;
    --spark-button-large-background: #508AFF;
}
</style>
```

| Variable | What it changes | Default |
| --- | --- | --- |
| `--spark-button-large-font-size` | Large button font size | `18px` |
| `--spark-button-large-padding` | Large button padding | `0.875em 1.75em` |
| `--spark-button-large-background` | Large button background | `#125EF8` |
| `--spark-button-large-background` | Large button background on hover | `#508AFF` |

### Messages

#### Toast notifications

Toast notifications are the short pop-up messages SparkLayer shows customers on screen.

```html title="Sample CSS Code"
<style>
:root {
    /* Toast notifications */
    --spark-toast-color: #FFFFFF;
    --spark-toast-text-color: #000000;
    --spark-toast-action-color: #125EF8;
    --spark-toast-border-color: #DDDDDD;
    --spark-toast-border-radius: 4px;
}
</style>
```

| Variable | What it changes | Default |
| --- | --- | --- |
| `--spark-toast-color` | Toast notification background colour | `#FFFFFF` |
| `--spark-toast-text-color` | Toast notification text colour | `#000000` |
| `--spark-toast-action-color` | Toast notification link colour | `#125EF8` |
| `--spark-toast-border-color` | Toast notification border colour | `#DDDDDD` |
| `--spark-toast-border-radius` | Toast notification border radius | `4px` |
| `--spark-toast-animation-display` | Whether a progress bar shows | `block` |

To hide toast notifications completely, add this CSS to your website:

```css
spark-toast {display: none;}
```

#### General messages

```html title="Sample CSS Code"
<style>
:root {
    /* General messages */
    --spark-message-padding: 0.7em 1.25em;
    --spark-message-success-background: #E5FFF5;
    --spark-message-success-border: 1px solid #1c9665;
    --spark-message-warn-background: #FDF7E3;
    --spark-message-warn-border: 1px solid #EDC35C;
    --spark-message-error-background: #E74148;
    --spark-message-error-border: 1px solid #E74148;
}
</style>
```

| Variable | What it changes | Default |
| --- | --- | --- |
| `--spark-message-padding` | Message box padding | `0.7em 1.25em` |
| `--spark-message-success-background` | Success message background | `#E5FFF5` |
| `--spark-message-success-border` | Success message border | `1px solid #1c9665` |
| `--spark-message-warn-background` | Warning message background | `#FDF7E3` |
| `--spark-message-warn-border` | Warning message border | `1px solid #EDC35C` |
| `--spark-message-error-background` | Error message background | `#E74148` |
| `--spark-message-error-border` | Error message border | `1px solid #E74148` |

### Forms

#### Input fields

```html title="Sample CSS Code"
<style>
:root {
    /* Input fields */
    --spark-form-field-text-transform: none;
    --spark-placeholder-text-color: #999999;
    --spark-input-border-color: #CCCCCC;
    --spark-input-border: 1px solid #CCCCCC;
    --spark-input-radius: 4px;
    --spark-input-background: #FFFFFF;
    --spark-input-error-color: #EF0000;
    --spark-input-success-color: #00AF76;
    --spark-input-focus-color: #125EF8;
    --spark-input-font-size: 14px;
    --spark-input-margin: 0;
    --spark-input-padding: 0.75em;
    --spark-label-font-size: 0.8em;
    --spark-input-disabled-color: #777777;
    --spark-input-disabled-solid-color: #949494;
}
</style>
```

| Variable | What it changes | Default |
| --- | --- | --- |
| `--spark-form-field-text-transform` | Form text transform | `none` |
| `--spark-placeholder-text-color` | Input field placeholder colour | `#999999` |
| `--spark-input-border-color` | Input field border colour | `#CCCCCC` |
| `--spark-input-border` | Input field border | `1px solid #CCCCCC` |
| `--spark-input-radius` | Input field border radius | `4px` |
| `--spark-input-background` | Input field background | `#FFFFFF` |
| `--spark-input-error-color` | Input field error colour | `#EF0000` |
| `--spark-input-success-color` | Input field success colour | `#00AF76` |
| `--spark-input-focus-color` | Input field focus colour | `#125EF8` |
| `--spark-input-font-size` | Input field font size | `14px` |
| `--spark-input-margin` | Input field margin | `0` |
| `--spark-input-padding` | Input field padding | `0.75em` |
| `--spark-label-font-size` | Label font size | `0.8em` |
| `--spark-input-disabled-color` | Disabled input field colour | `#777777` |
| `--spark-input-disabled-solid-color` | Disabled input border colour | `#949494` |

#### Radio buttons

```html title="Sample CSS Code"
<style>
:root {
    /* Radio buttons */
    --spark-radio-fill-color: #125EF8;
    --spark-radio-empty-color: #5A5A5A;
    --spark-radio-border: 2px solid #125EF8;
}
</style>
```

| Variable | What it changes | Default |
| --- | --- | --- |
| `--spark-radio-fill-color` | Selected radio button colour | `#125EF8` |
| `--spark-radio-empty-color` | Unselected radio button colour | `#5A5A5A` |
| `--spark-radio-border` | Radio button border | `2px solid #125EF8` |

#### Select menus

```html title="Sample CSS Code"
<style>
:root {
    /* Select menus */
    --spark-select-border: 1px solid #CCCCCC;
    --spark-select-background: #FFFFFF;
    --spark-select-focus: 1px solid #125EF8;
    --spark-select-font-size: 14px;
    --spark-select-padding: 0.75em;
    --spark-select-radius: 4px;
    --spark-select-disabled-color: #999999;
}
</style>
```

| Variable | What it changes | Default |
| --- | --- | --- |
| `--spark-select-border` | Select menu border | `1px solid #CCCCCC` |
| `--spark-select-background` | Select menu background | `#FFFFFF` |
| `--spark-select-focus` | Select menu border when focused | `#125EF8` |
| `--spark-select-font-size` | Select menu font size | `14px` |
| `--spark-select-padding` | Select menu padding | `0.75em` |
| `--spark-select-radius` | Select menu border radius | `4px` |
| `--spark-select-disabled-color` | Disabled select menu colour | `#999999` |

### Tables

```html title="Sample CSS Code"
<style>
:root {
    /* Tables */
    --spark-table-border-color: #CCCCCC;
    --spark-table-striped-color: #F5F5F5;
    --spark-table-header-background-color: #FFFFFF;
    --spark-table-header-text-color: #555555;
    --spark-table-header-font-weight: 500;
    --spark-table-header-font-size: 14px;
    --spark-table-header-text-transform: none;
    --spark-table-variants-border-color: #CCCCCC;
}
</style>
```

| Variable | What it changes | Default |
| --- | --- | --- |
| `--spark-table-border-color` | Table border colour | `#CCCCCC` |
| `--spark-table-striped-color` | Background of striped table rows | `#F5F5F5` |
| `--spark-table-header-background-color` | Table header background | `#FFFFFF` |
| `--spark-table-header-text-color` | Table header text colour | `#555555` |
| `--spark-table-header-font-weight` | Table header font weight | `500` |
| `--spark-table-header-font-size` | Table header font size | `14px` |
| `--spark-table-header-text-transform` | Table header text transform | `none` |
| `--spark-table-variants-border-color` | Border colour of the variants table on product pages | `#CCCCCC` |

### Product card

These variables style the [product card interface](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md): the product image, name, price, variant drop-downs, quantity selector and **Add** button shown on collection pages.

```html title="Sample CSS Code"
<style>
:root {
    /* Product Card */
    --spark-product-card-button-radius: 4px;
    --spark-product-card-button-padding: 0.75em 1em;
    --spark-product-card-pricing-font-size: 15px;
    --spark-product-card-pricing-font-size-small: 14px;
    --spark-product-card-select-min-height: 50px;

    --spark-product-card-stockstatus-fontsize: 16px;
    --spark-product-card-stockstatus-fontsize-small: 14px;
    --spark-product-card-stockstatus-align: center;
    --spark-product-stockstatus-back-order-display: none;

    --spark-product-card-tiered-pricing-display: flex;
    --spark-product-card-tiered-pricing-font-size: 12px;

}
</style>
```

| Variable | What it changes | Default |
| --- | --- | --- |
| `--spark-product-card-button-radius` | Button radius | `4px` |
| `--spark-product-card-button-padding` | Button padding | `0.75em 1em` |
| `--spark-product-card-pricing-font-size` | Price font size | `15px` |
| `--spark-product-card-pricing-font-size-small` | Price font size on mobile | `14px` |
| `--spark-product-card-select-min-height` | Minimum height of the select menu wrapper | `50px` |
| `--spark-product-card-stockstatus-fontsize` | Stock status font size | `16px` |
| `--spark-product-card-stockstatus-fontsize-small` | Stock status font size on mobile | `14px` |
| `--spark-product-card-stockstatus-align` | Stock status alignment | `center` |
| `--spark-product-card-tiered-pricing-display` | Display of the tiered (quantity) pricing information. Use `none` to hide it. | `flex` |
| `--spark-product-card-tiered-pricing-font-size` | Tiered pricing font size | `12px` |

### Dark mode

When [dark mode](#turn-on-dark-mode) is on, these variables control its colours.

| Variable | What it changes | Default |
| --- | --- | --- |
| `--spark-pdp-price-summary-color` | Default price colour | `#ffffff` |
| `--spark-dark-mode-lightest-color` | Default text colour | `#ffffff` |
| `--spark-dark-mode-status-in-stock` | In stock colour | `#5ecfad` |
| `--spark-dark-mode-status-back-order` | Back-order colour | `#96b1ef` |
| `--spark-dark-mode-status-out-of-stock` | Out of stock colour | `#ff9a9a` |
| `--spark-dark-mode-table-border-color` | Table border colour | `#555` |
| `--spark-dark-mode-table-header-background` | Table header colour | `#000` |
| `--spark-dark-mode-table-row-background` | Table row colour | `#333` |
| `--spark-dark-mode-table-row-alt-background` | Alternate table row colour | `#222` |
| `--spark-dark-mode-qty-background` | Quantity box colour | `#000` |
| `--spark-dark-mode-qty-background-hover` | Quantity box colour on hover | `#222` |
| `--spark-dark-mode-qty-border-color` | Quantity box border colour | `#555` |

## FAQs

**Can I change the colours without editing code?**

No. Colours and fonts are set with CSS in your theme, but you only need to change the 4 brand values in the [recommended starting CSS](#recommended-starting-css). If you'd rather not edit your theme, ask your developer or agency, or [contact us](mailto:contact@sparklayer.io). Dark mode is the one design setting you can turn on without code, at **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app.

**Why aren't my CSS changes showing?**

Check that the code is inside `:root { … }` in a `<style>` tag, that every variable starts with two hyphens (`--spark-…`), that each line ends with a semicolon, and that it's added to the theme your store is actually using. Then sign in as a B2B customer and refresh the page: SparkLayer's interfaces only load for signed-in B2B customers.

**My styles stopped working after I published a theme**

Check SparkLayer isn't loaded twice. On Shopify, this happens when the theme has the SparkLayer app embed turned on and also a SparkLayer script hard-coded in its code, for example in `theme.liquid`. Keep only the app embed, and remove the hard-coded script. See [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md).

**What if I can't style an element the way I want?**

If there's no variable for what you need, [contact us](mailto:contact@sparklayer.io) and we'll advise on the best approach. Some things can't be changed with CSS at all, such as the layout and button order of the product page widget, or a button's width. See [What you can and can't change](https://docs.sparklayer.io/help/storefront/what-you-can-change.md).

**Can I hide parts of the interfaces with CSS?**

Yes, for some elements. For example, you can hide the product image, SKU or pack price on product pages. See [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md) and [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md) for the variables.


---

# What you can and can't change on the storefront

URL: https://docs.sparklayer.io/help/storefront/what-you-can-change

See which parts of SparkLayer's storefront widgets you can change in settings, with CSS or custom slots, which need a developer, and which are fixed.

> **Quick summary**
>
> - Text, many features and the order of My Account sections and payment methods are settings at **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app. Colours, fonts and sizes are [CSS variables](https://docs.sparklayer.io/help/storefront/customising-design.md#variable-reference). Your own messages go in [custom slots](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md).
> - The layout of the product page widget and the order of its buttons are fixed. No setting or CSS variable changes them: only a custom script from your developer can.
> - Your theme's own parts, such as the cart count in your header, aren't SparkLayer's. Your theme or your developer controls them.
> - Our team installs the widgets for you, free, on every plan. That doesn't include customising your theme. See [Contact support](https://docs.sparklayer.io/help/support.md).

## At a glance

| You want to change | How | Who |
| --- | --- | --- |
| Wording, such as a button label | A translation override, in settings | You |
| Features such as favourites, shopping lists and the AI cart features | A setting | You |
| Colours, fonts, sizes, corners and spacing | CSS variables | You or your developer |
| Your own messages, banners and links | Custom slots | Your developer, usually |
| How products are laid out, such as a table or a matrix | An attribute in your theme's code | Your developer |
| The layout inside the product page widget, or its button order | A custom script | Your developer |
| Your theme's header, menus and cart count | Your theme | You or your theme developer |

## Change it yourself, in settings

These need no code. Go to **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app, change the setting, then click **Save and publish**. See [Storefront options](https://docs.sparklayer.io/help/storefront/storefront-options.md).

| What | Setting |
| --- | --- |
| Any text in the widgets, such as **Add to Cart**, in each language | **Translation overrides**. See [Change SparkLayer's text](https://docs.sparklayer.io/help/storefront/languages-and-international.md#change-sparklayers-text). |
| The order customers see payment methods in at checkout | **Checkout** > **Payment methods, in order** |
| Extra checkout fields, such as a PO number | **Checkout** > **Checkout fields**. See [Checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md). |
| The order of My Account sections, and which ones show | **My Account** > **Account sections, in order** |
| Favourites and shopping lists | **My Account** > **Favourites lists** and **Shopping lists** |
| Financial figures in My Account | **My Account** > **Hide financial figures** |
| The AI cart features | **Checkout** > **Hide AI features in the cart**. It hides the [Intelligent Cart](https://docs.sparklayer.io/help/ordering/intelligent-cart.md#hide-intelligent-cart) features, such as **Upload a file** and **Forward an email**. Other cart actions stay. |
| Dark colour scheme | **Pricing and display** > **Dark theme** |

Rules for each customer group, such as stock display, are set on the group at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app. Pack sizes and quantity limits are fields on your products: see [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md).

## Change it with CSS

Colours, fonts, font sizes, corner rounding and spacing each have a CSS variable. Set the ones you want in your theme: see [Customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md), and the [full list of variables](https://docs.sparklayer.io/help/storefront/customising-design.md#variable-reference) for your developer.

| What | Can you change it? |
| --- | --- |
| Brand colours and fonts | Yes, with 4 values. See [Change your brand colours and fonts](https://docs.sparklayer.io/help/storefront/customising-design.md#add-custom-css-to-your-store). |
| Button colours, font, corners and padding | Yes, with the [button variables](https://docs.sparklayer.io/help/storefront/customising-design.md#buttons). |
| Button width | No. There's no CSS variable for it. Padding changes the space around the text. |
| Some details on product pages, such as the image or SKU | Yes, hide them with a variable. See [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md#options-at-a-glance). |
| Toast notifications (the short pop-up messages) | Yes, style or hide them. See [Toast notifications](https://docs.sparklayer.io/help/storefront/customising-design.md#toast-notifications). |

If there's no variable for what you need, [contact us](https://docs.sparklayer.io/help/support.md) before your developer writes their own CSS, and we'll advise on the approach.

## Add your own content with slots

Custom slots show your own HTML inside the widgets, in 8 fixed places: the top of My Account and My Cart, under each cart line, the **Shipping** and **Review & Pay** checkout steps, the order complete screen, and above and below the purchase summary. You turn a slot on in settings, and your developer adds the content to your theme. See [Custom slots](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md).

You can't add content anywhere else inside the widgets, or move a slot.

## Needs a developer

| What | How your developer does it |
| --- | --- |
| Show products as a table, all variants or a matrix | An attribute on the widget in your theme. See [Change the product page layout](https://docs.sparklayer.io/help/storefront/product-display.md#change-the-product-page-layout). |
| Quick buy mode and 1-click ordering buttons | Code in your theme. See [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md). |
| The layout inside the product page widget, or the order of its buttons | A custom script. The layout and button order are fixed: no setting or CSS variable changes them. |
| Hide your theme's own prices and **Add to cart** buttons from B2B customers | Code in your theme. See the [frontend integration checklist](https://docs.sparklayer.io/developers/frontend.md#frontend-integration-checklist). |
| Show the header cart count for SparkLayer's cart | The [JavaScript SDK](https://docs.sparklayer.io/developers/javascript-sdk/cart.md). See [The cart count in your header](#the-cart-count-in-your-header). |
| Show the widgets in a different language from your store, or set one date and currency format for everyone | A Core Script setting. See [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md). |

A custom script changes SparkLayer's widgets from outside, so an update to SparkLayer can break it. Your developer looks after it.

## Can't be changed

- **Other cart actions.** **Hide AI features in the cart** removes the AI features, but there's no setting to hide the cart's other actions one by one.
- **Single variants for retail shoppers.** Shopify can't hide one variant of a product from retail shoppers. Make the variant a separate product and tag it `b2b-only` instead. See [What hides what](https://docs.sparklayer.io/help/storefront/product-settings.md#what-hides-what).
- **Shopify's new customer accounts.** If you use them, the account pages are Shopify's own and can't be restyled. SparkLayer's [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) area is separate.

## Language

SparkLayer's widgets show in your store's language. On Shopify, they follow the language the customer is browsing your store in (Shopify's locale), not the customer's browser settings. To change the wording in a language, use translation overrides. Product names and options come from your platform: to show them translated on Shopify, ask us to turn on product translations. See [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md).

## Page builders and copied themes

SparkLayer is installed in your theme's templates. Two set-ups often cause problems:

- **Page builder apps**, such as PageFly or Shogun. A page made with one uses its own layout, so it may not include SparkLayer's widgets. B2B customers can then see your retail prices and **Add to cart** buttons there. Check each page builder page signed in as a B2B customer.
- **A theme copied from another store.** It can carry the other store's SparkLayer code, such as its Core Script with that store's site ID. Remove that code and set SparkLayer up again on the copy: see [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md).

If you use either, tell us when you [request installation](https://docs.sparklayer.io/help/support.md), so we can check them.

## The cart count in your header

The cart icon and count in your header belong to your theme, not SparkLayer. SparkLayer's cart is separate from your theme's cart, so for B2B customers the count can show 0, or items added before they signed in. Hide the count for B2B customers, or have a developer keep it in step with SparkLayer's cart using the [JavaScript SDK](https://docs.sparklayer.io/developers/javascript-sdk/cart.md). Our team can hide it for you.

## What the free installation covers

Our team installs SparkLayer's widgets on your theme for you, free, on every plan, and checks they work. Theme customisation isn't included: restyling the widgets, custom scripts, page builder pages and changes to your theme's own design. Your developer or agency does those. See [Contact support](https://docs.sparklayer.io/help/support.md).

## Next steps

- [Customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md): Brand colours, fonts and every CSS variable
- [Storefront options](https://docs.sparklayer.io/help/storefront/storefront-options.md): Every setting you can change without code
- [Custom slots](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md): Add your own content inside the widgets
- [Troubleshooting](https://docs.sparklayer.io/help/troubleshooting.md): Fixes for widgets that don't load or look wrong


---

# How products are shown

URL: https://docs.sparklayer.io/help/storefront/product-display

Change how B2B customers see products: table and variant views, SKUs and barcodes, hidden variants, quick buy mode, favourites and 1-click ordering buttons.

> **Quick summary**
>
> - You can change how B2B customers see products in the [product detail](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) and [product card](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) interfaces: layout, variant views, SKUs, barcodes, stock and button text.
> - Most options are a small change to your theme's code or [custom CSS](https://docs.sparklayer.io/help/storefront/customising-design.md), usually made by your developer or agency. Hiding variants uses a product [metafield](https://docs.sparklayer.io/help/glossary.md#metafields).
> - Text changes, such as button labels, and turning off favourites need no code: you make them at **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app.
> - Every option is available on every plan. Quick buy mode, product customisations and 1-click ordering buttons need a developer.

## How it works

Two interfaces show your products to signed-in B2B customers:

- The **product detail interface** loads on product pages. In your theme's code it's the `<spark-pdp>` tag.
- The **product card interface** loads wherever a product card appears, such as collection pages. In your theme's code it's the `<spark-product-card>` tag.

Each option on this page starts with what customers see, then how to set it up. Most of the set-up is for whoever edits your theme. There are 4 ways to change what the interfaces show:

| Method | What you change | Where |
| --- | --- | --- |
| Tag setting (attribute) | Layout and what's shown, for example `mode-table-only` or `show-sku` | Your theme's code, inside the `<spark-pdp>` or `<spark-product-card>` tag |
| CSS variable | Hide elements, for example the image or SKU | Your [custom CSS](https://docs.sparklayer.io/help/storefront/customising-design.md) |
| Text (translation) | Labels and button text | The [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting), or a translation override at **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app (see [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md)) |
| Metafield | Hide or block specific variants | Your eCommerce platform's product data |

If someone else looks after your theme, use [Options at a glance](#options-at-a-glance) to tell them what you'd like changed. The code examples on this page use `{{ product.id }}`, which is Shopify's variable for the product ID. On other platforms, replace it with your platform's equivalent.

## Options at a glance

| What you want | Interface | How |
| --- | --- | --- |
| Show every product as a table, even with one variant | Product detail | `mode-table-only` |
| Show all variants in one table | Product detail | `mode-all-variants` |
| Show variants in a matrix | Product matrix | `<spark-product-matrix>` |
| Hide the variant image in the table | Product detail | `--spark-pdp-image: none;` |
| Hide the SKU | Product detail | `--spark-pdp-sku: none;` |
| Show the barcode | Product detail, product card | `show-barcode` |
| Show stock status | Product card | `show-stock` |
| Show the SKU | Product card | `show-sku` |
| Hide variant drop-downs | Product card | `hide-dropdown="Size, Colour"` |
| Hide the price on the **Add** button | Product card | Translation `product-card.add-to-order.cta-text` (no code, at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app) |
| Show products as table rows on collection pages | Product card | `mode-quick-buy` |
| Hide a variant or make it unavailable | Product detail, product card | `sparklayer.settings` metafield |

## Change the product page layout

These options change how customers see a product on its product page.

### Show every product as a table

By default, a product with a single variant shows customers a quantity selector and an **Add to Order** button. Table-view mode shows every product in the table layout used for multi-variant products, with **Item**, **Price**, **Stock** and **Qty** columns, even if it only has one variant.

Your developer adds `mode-table-only` to the product detail tag:

```html
<spark-pdp parent-id="{{ product.id }}" mode-table-only></spark-pdp>
```

### Show all variants in one table ("All Variants" mode)

If your products have more than one variant option (for example colour and size), "All Variants" mode lists every variant in one table. Customers see this instead of the standard drop-down menus.

Your developer adds `mode-all-variants` to the product detail tag on your product pages:

```html
<spark-pdp parent-id="{{ product.id }}" mode-all-variants></spark-pdp>
```

The table lists variants in the same order as your product catalogue. In Shopify, that's the order of the options and values in the product's **Variants** section.

All Variants mode adds a column for each option, which can make the table too wide for phones. To hide columns on mobile, list them in `hide-on-mobile`:

```html
<spark-pdp parent-id="{{ product.id }}" hide-on-mobile="colour,size" mode-all-variants></spark-pdp>
```

### Show variants as a matrix ("Matrix" mode)

If your products have more than one variant option, the [product matrix interface](https://docs.sparklayer.io/help/storefront/interfaces/product-matrix.md) shows them to customers as a grid. Customers can then add many variants to an order quickly. You can use it anywhere products appear on your site.

Your developer adds the product matrix tag to your product pages:

```html
<spark-product-matrix parent-id="{{ product.id }}"></spark-product-matrix>
```

To show the restock date in the matrix, they add `show-restock-date`:

```html
<spark-product-matrix parent-id="{{ product.id }}" show-restock-date></spark-product-matrix>
```

See [Product matrix](https://docs.sparklayer.io/help/storefront/interfaces/product-matrix.md) for how it works and how to set it up.

### Hide the image in the table view

The product detail table shows customers a thumbnail of each variant. To hide the image, you or your developer add this to your [custom CSS](https://docs.sparklayer.io/help/storefront/customising-design.md):

```html
<style>
:root {
    /* Default */
    --spark-pdp-image: table-cell;

    /* Add this to hide image */
    --spark-pdp-image: none;
}
</style>
```

## Show or hide product details on product pages

These options change which product details customers see on product pages.

### Product code (SKU)

The product detail interface shows customers the product code (SKU), labelled **Product Code**, for single-variant and multi-variant products. To hide the SKU, you or your developer add this to your [custom CSS](https://docs.sparklayer.io/help/storefront/customising-design.md):

```html
<style>
:root {
    /* Default */
    --spark-pdp-sku: block;

    /* Add this to hide the SKU */
    --spark-pdp-sku: none;
}
</style>
```

To change the **Product Code** label without code, add a translation override for `pdp.product-code` at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app.

**For developers: set the label in the Core Script**

Set it in your Core Script instead (see [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md)):

```javascript title="Core Script"
translations: {
  en: {
    "pdp.product-code": "Product Code",
  }
},
```

### Barcode (ISBN, UPC, GTIN)

If your products have barcodes, SparkLayer can show customers them next to the product code, labelled **Barcode**. It uses the barcode stored against each variant in your eCommerce platform (in Shopify, the **Barcode (ISBN, UPC, GTIN, etc.)** field).

To show barcodes on product pages, your developer adds `show-barcode` to the product detail tag. To show them on collection pages too, they add it to the product card tag as well (see [Show the barcode on product cards](#show-the-barcode)).

```html
<spark-pdp show-barcode parent-id="{{ product.id }}"></spark-pdp>
```

To change the **Barcode** label without code, add a translation override for `global.product.barcode` at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app.

**For developers: set the label in the Core Script**

```javascript title="Core Script"
translations: {
  en: {
    "global.product.barcode": "Barcode",
  }
},
```

### Stock levels

To show live stock levels, pre-orders and restock dates, see [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md).

## Customise product cards

These settings change what customers see on the [product card interface](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md), everywhere it appears. Each one is a setting your developer adds to the product card tag.

### Show stock status

Shows customers the stock status under the **Add** button, for example **In stock** with **100+ available**.

```html
<spark-product-card show-stock parent-id="{{ product.id }}"></spark-product-card>
```

### Show the product code (SKU)

Shows customers **Product Code** with the SKU under the **Add** button.

```html
<spark-product-card show-sku parent-id="{{ product.id }}"></spark-product-card>
```

### Show the barcode

Shows customers **Barcode** with the variant's barcode under the **Add** button.

```html
<spark-product-card show-barcode parent-id="{{ product.id }}"></spark-product-card>
```

### Hide variant drop-downs

Hides the drop-down menu for one or more variant options. For example, if a product's only **Size** option has one value, you might not want to show customers a **Size** drop-down. Replace `Size, Colour` with the option names from your platform:

```html
<spark-product-card hide-dropdown="Size, Colour" parent-id="{{ product.id }}"></spark-product-card>
```

### Hide the price on the Add button

By default, customers see the total price on the product card button, for example **Add (US$34.50)**. The text comes from the `product-card.add-to-order.cta-text` translation, where `{price}` is the total.

To show just **Add**, add a translation override for `product-card.add-to-order.cta-text` at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app with the text `Add`. You don't need code.

**For developers: change it in the Core Script**

Remove `({price})` from the text in your Core Script:

```javascript title="Core Script"
translations: {
  en: {
     "product-card.add-to-order.cta-text":"Add ({price})",
 }
},
```

## Hide variants or make them unavailable

In the product detail and product card interfaces, you can apply rules to specific variants:

| Rule | What customers see |
| --- | --- |
| **Hide specific variants** | The variant doesn't appear in SparkLayer's interfaces. You can hide it from all B2B customers or from specific customer groups. |
| **Make specific variants un-sellable** | The variant appears, but shows **Unavailable** instead of a quantity selector, so it can't be added to an order. |

For the whole job, including hiding products from your store's pages, see [Hide products from customers](https://docs.sparklayer.io/help/guides/hide-products.md).

**Unavailable** also shows, more often, when the customer's price list has no price for the variant. See [Why a product shows Unavailable](https://docs.sparklayer.io/help/pricing/managing-pricing.md#unavailable). To hide a product from your theme's collection and product pages as well as SparkLayer's interfaces, see [What hides what](https://docs.sparklayer.io/help/storefront/product-settings.md#what-hides-what). To show "Price on application" instead, see [Show "price on application"](https://docs.sparklayer.io/help/pricing/managing-pricing.md#price-on-application).

Both rules use the `sparklayer.settings` metafield, a JSON field stored against the variant. [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md) explains all the settings it can hold.

1. Make sure the field exists. On Shopify, 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 and, in the **Metafields** card, click **Configure** next to **SparkLayer metafields**. On other platforms, see the [developer docs](https://docs.sparklayer.io/developers.md).
2. In the form below, choose who shouldn't see the variants, and **Hide them** or **Show them, but stop orders**. It writes the value for you.
3. Click **Copy**, open the variant in your platform's admin, paste the value into the `sparklayer.settings` field and save. Or click **Ask Claude** or **Ask ChatGPT** to have your AI assistant apply it to many products.

**Lots of products? Fill them in one table (Shopify):** in your Shopify admin, go to **Products**, tick the products and click **Edit products**. Click **Columns**, tick the SparkLayer field under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

**Field details, if you add the field by hand**

| Field | Value |
| --- | --- |
| **Custom data type** | Variants (on Shopify, **Settings > Custom data > Variants** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data/productvariant/metafields))) |
| **Metafield type** | `JSON` |
| **Namespace** | `sparklayer` |
| **Key** | `settings` |
| **Value to hide a variant** | `[{"customer_group":"base","display":false}]` |
| **Value to make a variant un-sellable** | `[{"customer_group":"base","sell":false}]` |

## Let customers save favourites

B2B customers can save products for later with a heart icon (**Add to favourites**). It appears next to the **Add to cart** button in the product detail interface, and on product cards on collection pages. Saved products are listed in a **Favourites** section in My Account, where customers can add them to the cart. See [Favourites](https://docs.sparklayer.io/help/ordering/favourites.md).

Favourites are on by default. To turn them off:

1. Go to **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app.
2. Open **My Account** and turn off **Favourites lists**.
3. Click **Save and publish**.

## Turn on quick buy mode

Quick buy mode shows customers the products on a collection page as table rows. Each row has the product image, name, price, variant drop-downs, a quantity selector and an **Add** button. Customers can build an order without opening each product page.

How much work this takes depends on how your store is set up. Our team can advise on the approach, but may not be able to make the changes on your store, so we recommend working with a developer.

Your developer adds `mode-quick-buy` to the product card tag on any collection page:

```html
<spark-product-card mode-quick-buy parent-id="{{ product.id }}"></spark-product-card>

```

### Set up quick buy mode on Shopify

**Shopify only:**

The [Shopify B2B Dawn theme](https://docs.sparklayer.io/help/platforms/shopify/dawn-theme.md) has quick buy mode turned on by default. Your developer can add it to most other Shopify themes:

1. In your theme code, in `/templates/`, duplicate your default collection template.
2. In `/sections/`, duplicate your default collection section.
3. In `/snippets/`, create a new file with [the quick buy snippet code](https://gist.github.com/cm-sl/3f417dbbd944998671ed44fce348c655).
4. Change the new collection section so it renders the new snippet, which has quick buy mode turned on.
5. Add [the quick buy CSS](https://gist.github.com/cm-sl/29f2adf01ec0e522479a55fe59fc3fad) to your theme.
6. In the Shopify admin, go to **Products > Collections** ([open in the Shopify admin](https://admin.shopify.com/collections)) and open the collection you want to change.
7. Under **Theme template**, choose the quick buy template and click **Save**.

Quick buy mode also applies to customers who aren't signed in. To change that, we recommend working with a Shopify expert.

## Product customisations

If you sell products that customers personalise, for example with custom text, SparkLayer can capture those details. Customers add their custom text to products in their order, and it's sent to your eCommerce platform with the order. In the cart, a line with customisations shows **Customizations active**, and hovering over it shows the details.

This is an advanced setup that needs a developer, using SparkLayer's JavaScript SDK. See the JavaScript SDK in the [developer docs](https://docs.sparklayer.io/developers.md).

## Add 1-click ordering buttons (Spark Buttons)

Spark Buttons let customers add a set of products to their order in one click, instead of one at a time. You can put them anywhere on your store, such as the homepage or a landing page.

Try them on our [B2B demo store](https://b2b-demo-store-usd.myshopify.com/pages/b2b-bundles). You'll need to sign in first.

Use Spark Buttons to point B2B customers to a specific range, for example:

- A starter pack for new customers, such as your best-selling products
- A curated range, such as a new season's products
- A bundle, such as the top 10 products from a category

After the products are added, customers can change the order as normal, for example by editing quantities or removing items.

### Add a Spark Button

Each button is a short piece of JavaScript that lists the SKUs and quantities to add. Spark Buttons need custom JavaScript, so you may want a Shopify expert to help. Because each setup is custom, our team may not be able to advise on the best approach.

Your developer adds the code wherever you want the buttons to appear.

**Example code for your developer**

This example has 2 buttons, each adding different SKUs and quantities:

```html
<!-- Example Spark Button 1 -->
<a href="#" data-add-to-cart="">Add to order</a> 

<script>
// <![CDATA[
    document.querySelector('[data-add-to-cart]').addEventListener('click', function () {
    const products = {
    products: [
        {
            sku: 'SKU-123',
            absoluteQuantity: 5,
        },
        {
            sku: 'SKU-789',
            absoluteQuantity: 5,
        },
    ],
  };
  window.spark.updateCart(products);
});
// ]]>
</script>

<!-- Example Spark Button 2 -->
<a href="#" data-add-to-cart-2="">Add to order</a> 

<script>
// <![CDATA[
    document.querySelector('[data-add-to-cart-2]').addEventListener('click', function () {
    const products = {
    products: [
        {
            sku: 'SKU-ABC',
            absoluteQuantity: 10,
        },
        {
            sku: 'SKU-XYZ',
            absoluteQuantity: 10,
        },
    ],
  };
  window.spark.updateCart(products);
});
// ]]>
</script>
```

| Item | Details |
| --- | --- |
| **Several buttons on one page** | Give each button a unique selector. The example above uses `data-add-to-cart` and `data-add-to-cart-2`. |
| **Product SKUs** | Each SKU must exist in your store. |
| **Quantities** | Set the quantity with `absoluteQuantity`. If the SKU has a pack size, the quantity is rounded up to fit it. |

## Show products to B2B customers only

If you sell to retail (DTC) and B2B customers from the same store, you may have products that only signed-in B2B customers should see and buy. For example, products sold in large volumes, or B2B exclusives.

**Shopify only:**

On Shopify, use the free [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md) app to mark products as B2B-only or B2C-only. For other ways to do this, see [Shopify customisations](https://docs.sparklayer.io/help/platforms/shopify/customisations.md).

## Change the "Add to Cart" button text

To change the text customers see on the add buttons in the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md), add translation overrides for these keys at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app. You don't need code. In the text, `{price}` is replaced with the total price.

**For developers: set the text in the Core Script**

```javascript title="Core Script"
translations: {
  en: {
    "product-card.add-to-order.cta-text": "Add ({price})",
    "pdp.add-to-order.cta-text": "Add to Cart ({price})"
  }
},
```

## FAQs

**Where do I add the tag settings?**

In your theme's code, where the `<spark-pdp>`, `<spark-product-card>` or `<spark-product-matrix>` tag appears. If you're not sure where that is, see the setup guide for each interface under [Storefront widgets](https://docs.sparklayer.io/help/storefront/interfaces.md), or ask your developer.

**Why doesn't the product ID variable work on my platform?**

`{{ product.id }}` is Shopify's variable. On other platforms, replace it with the variable your platform's templates use for the product ID.

**Can I change the text without editing the Core Script?**

Yes. Go to **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app and add a translation override for the text key, such as `pdp.product-code`. See [Storefront options](https://docs.sparklayer.io/help/storefront/storefront-options.md).


---

# Stock display

URL: https://docs.sparklayer.io/help/storefront/stock-display

Show live stock levels to B2B customers, allow pre-orders and back-orders, add restock dates, choose stock locations and reserve stock for retail customers.

> **Quick summary**
>
> - B2B customers see a stock status on each product, such as **In stock** or **Pre-order**, and can see the number of units. SparkLayer shows the same stock (inventory) levels as your eCommerce platform. It doesn't keep separate stock.
> - You choose what each customer group sees in the group's **Stock display** rule, at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app: stock status, exact units up to a maximum, and low and last stock thresholds. This needs Core Script version 2.0 or later.
> - Pre-orders and back-orders follow your platform's "continue selling when out of stock" setting. They aren't supported on BigCommerce. Restock dates, pre-order limits and reserved stock use product [metafields](https://docs.sparklayer.io/help/glossary.md#metafields) (extra fields on each variant), which Wix doesn't support.
> - Stock locations show a customer group stock from one location. Turn on **Multi-location stock** at **Settings > Configurations > Ordering** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Ordering** in the Shopify app, then set each group's **Stock location** rule.

## How it works

SparkLayer reads stock from your eCommerce platform, or from your own system if you send it through the [SparkLayer API](https://docs.sparklayer.io/developers/api.md). Whether you manage stock by hand or from an ERP, B2B customers see the same numbers. The customer group's stock display settings then decide how customers see that stock.

How a stock status reaches the customer:

1. **Stock in your platform**: Quantities and "continue selling" settings for each variant
2. **Customer group rules**: Whether to show stock, exact units, and the max, low and last thresholds
3. **Status shown**: In stock, low stock, last stock, out of stock or pre-order, in the frontend interfaces

### How the status is chosen

SparkLayer works from the **available** quantity of each variant. On Shopify, that's the **Available** quantity: stock on hand minus units committed to open orders. For example, 1 unit on hand that's committed to an order counts as 0 available, so with **Continue selling when out of stock** on, the variant shows as pre-order.

Customers see one of these statuses, each with a coloured dot:

| Status | Colour | When it shows |
| --- | --- | --- |
| **In stock** | Green | Available stock is above the **Low** threshold. If you show units, stock above **Max** shows as, for example, **100+**. |
| **Low stock** | Amber | Available stock is above 0 and at or below the **Low** threshold. Customers see the number of units left. |
| **Last stock** | Amber | Only the last items are left, as set by the **Last** threshold. |
| **Pre-order** | Blue | Available stock is 0 or less, and your platform allows the variant to be sold when it's out of stock. See [pre-orders and back-orders](#allow-pre-orders-and-back-orders). |
| **Out of stock** | Red | Available stock is 0 or less, and selling when out of stock is off. The variant can't be ordered. |
| **Unavailable** | Red | Usually, the customer's price list has no B2B price for the variant. See [Why a product shows Unavailable](https://docs.sparklayer.io/help/pricing/managing-pricing.md#unavailable). It also shows when the variant has been made un-sellable: see [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md#hide-variants-or-make-them-unavailable). To show "Price on application" instead, see [Show "price on application"](https://docs.sparklayer.io/help/pricing/managing-pricing.md#price-on-application). |

Stock labels that come from your own theme, rather than from SparkLayer's interfaces, aren't changed by any of the settings on this page.

### Which setting hides which label

All of these are in the customer group's **Stock display** rule, at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app:

| To hide | Do this |
| --- | --- |
| **In stock**, **Low stock**, **Last stock** and **Out of stock** | Untick **Show stock availability to customers**. This doesn't hide the pre-order label. |
| The **Pre-order** label | Tick **Hide pre-order**. |
| The exact number of units | Untick **Show number of units of stock**. |

## Show stock levels to customers

You choose what each customer group sees. Stock display settings need version 2.0 or later of the Core Script, the SparkLayer code in your theme. If you're not sure which version you have, ask your developer or see [How do I show stock on a SparkLayer version before 2.0?](#for-versions-of-sparklayer-before-20).

1. 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 click a group's name. To apply the settings to every group, click **Edit** on the base customer group instead: the other groups inherit from it.
2. Under **Inherited rules**, click **+ Override** next to **Stock display** (on the base group, **+ Customize**). The rule moves up to **Customized rules**.
3. Click **Configure** and tick **Show stock availability to customers**.
4. To show exact numbers, tick **Show number of units of stock** and enter the **Max**, **Low** and **Last** values.
5. Click **Save**.

Changes to a customer group's rules apply straight away. There's nothing to publish and no sync to wait for.

| Setting | What it does |
| --- | --- |
| **Show stock availability to customers** | Customers see the stock status of each product and variant. Pre-order is always shown unless **Hide pre-order** is ticked. |
| **Hide pre-order** | Hides the pre-order stock status from customers. |
| **Show number of units of stock** | Shows the exact stock number, up to the **Max** value. |
| **Max** | The highest number shown, in green. Anything above shows as, for example, **100+**. |
| **Low** | The low stock threshold. Low stock shows in amber. |
| **Last** | The last stock threshold, for the last remaining items. |

### Show the stock key on desktop

On smaller screens, customers see a stock key under the variants table in the [product detail interface](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) when stock display is on. It explains each colour: **In stock**, **Out of stock**, **Pre-order**, **Low stock** and **Last stock**.

To show the stock key on larger screens too, you or your developer add this line to your [custom CSS](https://docs.sparklayer.io/help/storefront/customising-design.md):

```css
--spark-pdp-stock-key-desktop: flex;
```

### Set a stock level display limit

To cap the stock number customers see on product pages, go to **Settings > Configurations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations** in the Shopify app and enter a number in **Stock level display limit**. For example, with a limit of `100`, customers see `100+` when you have more than 100 in stock.

### Show stock on product cards

The [product card interface](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) can show customers live stock on collection pages too. See [Show stock status](https://docs.sparklayer.io/help/storefront/product-display.md#show-stock-status).

## Allow pre-orders and back-orders

Customers can add a pre-order (or back-order) product to an order even when it's out of stock. They see a pre-order message next to it, such as **On Backorder** or **Pre-order**.

### Set up pre-orders on Shopify

**Shopify only:**

1. In the Shopify admin, open the product or variant.
2. In the inventory section, tick **Track quantity** and **Continue selling when out of stock**.
3. Set the **Available** quantity to 0 or less, then click **Save**.

"Continue selling when out of stock" applies to retail customers too, so they can also buy more than you have. To limit this, you can create separate products that only B2B customers see. See [Sell pre-order products to B2B customers only](#sell-pre-order-products-to-b2b-customers-only).

On other platforms, see the [developer docs](https://docs.sparklayer.io/developers.md). Pre-orders and back-orders aren't supported on BigCommerce (see [Compare platforms](https://docs.sparklayer.io/help/platforms/compare.md)).

### Change the pre-order message

You can change the pre-order message customers see without code. At **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app, add a translation override for `pdp.messaging.back-order` (product page) and `product-card.messaging.back-order` (product cards). See [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md).

**For developers: set the text in the Core Script**

```javascript title="Core Script"
translations: {
  en: {
    "pdp.messaging.back-order": "Pre-order",
    "product-card.messaging.back-order": "Pre-order",
  }
},
```

### Limit how many units can be pre-ordered

You can set exactly how much stock of a variant customers can pre-order or back-order. Use the `sparklayer.min_stock_level` metafield, entered as a negative number: `-20` lets customers order until stock reaches -20.

1. Make sure the field exists. On Shopify, 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 and, in the **Metafields** card, click **Configure** next to **SparkLayer metafields**. On other platforms, use the [metafield reference](#metafield-reference).
2. On each variant, set `sparklayer.min_stock_level` to a negative whole number, for example `-6`, `-12` or `-20`.

**Lots of products? Fill them in one table (Shopify):** in your Shopify admin, go to **Products**, tick the products and click **Edit products**. Click **Columns**, tick the SparkLayer field under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

**Set a different limit for each stock location**

If you use [stock locations](#stock-locations-inventory-locations), you can set the level for each location instead, with the `sparklayer.stock_location_data` field. Enter each location's ID from your eCommerce platform and its limit, and the form writes the value, for example `[{"location_id":"123","min_stock_level":-150}]`:

### Show a restock date

A restock date tells customers when a pre-order product is expected, for example "Pre-order. Expected shipping date: 17th April". Use it for a "due in" date (when you expect stock) or an "estimated shipping" date (when you expect to ship).

1. Make sure the `sparklayer.restock_date` field exists. On Shopify, 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 and click **Configure** next to **SparkLayer metafields**: it adds **B2B - Restock Date**. On other platforms, create it with the type `date` (see the [metafield reference](#metafield-reference)).
2. On each variant, set the date, for example `17/11/2022` for the UK format.

**Lots of products? Fill them in one table (Shopify):** in your Shopify admin, go to **Products**, tick the products and click **Edit products**. Click **Columns**, tick **B2B - Restock Date** under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

**Set a different restock date for each stock location**

If you use [stock locations](#stock-locations-inventory-locations), you can set a restock date for each location with the `sparklayer.stock_location_data` field. Enter each location's ID and pick its date, and the form writes the value, for example `[{"location_id":"123","restock_date":"2023-12-12"}]`:

To change the restock date wording, add a translation override for `pdp.messaging.back-order-due` at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app. In the text, `{restockDate}` is replaced with the date.

**For developers: set the text in the Core Script**

```javascript title="Core Script"
translations: {
  en: {
    "pdp.messaging.back-order-due": "Due {restockDate}",
  }
},
```

The [product matrix](https://docs.sparklayer.io/help/storefront/product-display.md#show-variants-as-a-matrix-matrix-mode) can show restock dates too, with the `show-restock-date` setting.

### Sell pre-order products to B2B customers only

If you sell to retail (DTC) and B2B customers from one store, you may want B2B customers to pre-order products that retail customers can't buy, for example a pre-season range.

**Shopify only:**

Shopify can't hide or show products, or single variants, by customer type on its own. Make the pre-order version a separate product:

1. Create a new product (or range) and set it up as normal, with images and descriptions.
2. Tag it `b2b-only` with the free [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md) app, so only signed-in B2B customers see it.
3. In SparkLayer, set up B2B pricing and any settings the products need, such as [quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md).

Retail customers then can't see these products. This duplicates some product data, but it keeps pre-order products for B2B customers only. A product already in a cart, or added with an add-to-cart link, can still be bought: see [B2B Catalogs limitations](https://docs.sparklayer.io/help/storefront/b2b-catalogs/limitations.md#hidden-product-add-to-cart-caveats).

### Tag orders that contain pre-order products (Shopify)

**Shopify only:**

The [Shopify Flow](https://apps.shopify.com/flow) app can tag orders that contain pre-order products automatically, so your team can find and handle them separately.

The sample Shopify Flow workflow:

1. **Order created**: The workflow starts when an order (or draft order) is created
2. **Check product tags**: Checks whether a product's tags include b2b-pre-order
3. **Tag the order**: Adds the order tag b2b-pre-order
4. **Add a note**: Updates the order note to say the order contains pre-order items and may need review before fulfilment

**Step 1.** **Tag your pre-order products**

In the Shopify admin, add the tag `b2b-pre-order` to each product you're selling on pre-order or back-order.

**Step 2.** **Tag orders with Shopify Flow**

Install the [Shopify Flow app](https://apps.shopify.com/flow) and create 2 workflows, one starting from **Order created** and one from **Draft order created**. In each, check whether any line item's product has the tag `b2b-pre-order`, and if it does, add the tag `b2b-pre-order` to the order. Once they're turned on, orders and draft orders containing pre-order products get the tag. [Our support team](https://docs.sparklayer.io/help/support.md) can help you set them up.

**Step 3.** **Filter your orders**

In the Shopify admin, go to **Orders** ([open in the Shopify admin](https://admin.shopify.com/orders)), click **Add filter** and filter by the tag `b2b-pre-order`. You can save this as a view, for example **Pre-Order**, and use it for your internal workflows, such as how you fulfil these items.

### Hide pre-order messages

Customers see a product as pre-order when it meets your store's pre-order criteria. On Shopify, that's when **Track quantity** is on, **Continue selling when out of stock** is on, and the **Available** quantity is 0 or less. You can hide the message in 2 ways:

| Where | How | Effect |
| --- | --- | --- |
| **In SparkLayer** | 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, open a customer group and, in its **Stock display** rule, tick **Hide pre-order**. | The pre-order status is hidden in the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) for that group. |
| **On Shopify** | Turn off **Track quantity** or **Continue selling when out of stock** for the product or variant. | The product is no longer treated as pre-order. On other platforms, see the [developer docs](https://docs.sparklayer.io/developers.md). |

## Stock locations (inventory locations)

If your store keeps stock in several locations, for example by region, you can choose which location's stock a customer group sees. Stock locations need the Growth plan or above.

1. Go to **Settings > Configurations > Ordering** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Ordering** in the Shopify app and turn on **Multi-location stock**, then save.
2. 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 click a group's name.
3. Under **Inherited rules**, click **+ Override** next to **Stock location**, then **Configure**.
4. Select a location, for example **London Warehouse**.
5. Click **Save**. **Reset** hands the rule back to the base group.

Until a group has a stock location, customers see combined stock from all locations. Each customer group can use one location.

This only changes the stock customers see. It doesn't change which location fulfils the order in your eCommerce platform.

On Shopify, your active locations sync to SparkLayer automatically. On other platforms, stock locations are managed through the [Stock API](https://docs.sparklayer.io/developers/api/stock.md). See [Set a stock location](https://docs.sparklayer.io/help/customers/customer-groups.md#set-a-stock-location) for the setup needed on each platform.

## Reserve stock for retail customers

If you run retail (DTC) and B2B from one store, both share the same stock, so large B2B orders could leave nothing for retail customers. A reserve stock quantity keeps some stock back for retail:

How reserved stock works, with a reserve of 50:

1. **Reserve set**: You set a reserve stock quantity on a variant, for example 50
2. **Both can order**: Retail and B2B customers can both order the product
3. **Stock reaches 50**: B2B customers can no longer add it to their order
4. **Retail keeps ordering**: Retail customers can still buy the reserved stock

To set it:

1. Make sure the `sparklayer.reserve_stock_quantity` field exists. On Shopify, 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 and, in the **Metafields** card, click **Configure** next to **SparkLayer metafields**: it adds **B2B - Reserved DTC Stock Quantity**. On other platforms, see the [metafield reference](#metafield-reference).
2. On each variant, enter the quantity to keep back, for example `50`, and save.

**Lots of products? Fill them in one table (Shopify):** in your Shopify admin, go to **Products**, tick the products and click **Edit products**. Click **Columns**, tick **B2B - Reserved DTC Stock Quantity** under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

To reserve a different amount for each customer group, use [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md).

## Change stock status messages

When stock display is on, you can change the wording of each stock status customers see. You don't need code: add a translation override for its key at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app. See [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md).

| Key | Default text |
| --- | --- |
| `pdp.messaging.back-order` | Pre-order |
| `pdp.messaging.back-order-due` | Due `{restockDate}` |
| `pdp.messaging.out-of-stock` | Out of stock |
| `pdp.messaging.low-stock` | Low stock |
| `pdp.messaging.last-stock` | Last stock |
| `pdp.messaging.in-stock` | In stock |
| `pdp.messaging.un-sellable` | Unavailable |

**For developers: set the text in the Core Script**

```javascript title="Core Script"
translations: {
  en: {
    "pdp.messaging.back-order": "Pre-order",
    "pdp.messaging.back-order-due": "Due {restockDate}",
    "pdp.messaging.out-of-stock": "Out of stock",
    "pdp.messaging.low-stock": "Low stock",
    "pdp.messaging.last-stock": "Last stock",
    "pdp.messaging.in-stock": "In stock",
    "pdp.messaging.un-sellable": "Unavailable",
  }
},
```

## Metafield reference

This reference is for whoever sets up your product data. All of these are variant metafields with the namespace `sparklayer`. On Shopify, create them at **Settings > Custom data > Variants** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data/productvariant/metafields)). On other platforms they're variant-level product fields: see the [developer docs](https://docs.sparklayer.io/developers.md) and your platform's metafields guide.

| Key | Type | Value | Used for |
| --- | --- | --- | --- |
| `min_stock_level` | `integer` | A negative whole number, for example `-6`, `-12` or `-20` | [Limit pre-order quantity](#limit-how-many-units-can-be-pre-ordered) |
| `restock_date` | `date` | A date in your store's format, for example `17/11/2022` (UK) | [Restock date](#show-a-restock-date) |
| `stock_location_data` | `json` | One entry per location, with the `location_id` from your platform and a `min_stock_level` and/or `restock_date` (`YYYY-MM-DD`) | Per-location pre-order limits and restock dates (Shopify) |
| `reserve_stock_quantity` | `integer` | A whole number, for example `50` | [Reserved stock](#reserving-stock) |

## Troubleshooting

**Diagnose: Stock labels or numbers looking wrong?** Find which setting controls what B2B customers see.

1. **What’s happening?** Sign in as a B2B customer, then pick the closest match.
   - A stock label still shows after I turned stock display off: go to question 2
   - The stock number differs from Shopify: go to question 3
   - It says pre-order or back-order, but there’s stock: go to fix A (Units committed to orders aren’t available)
   - No stock messages show at all: go to question 4
2. **Which label is still showing?** Each label is controlled separately.
   - Pre-order: go to fix B (Tick “Hide pre-order” on the group)
   - In stock, low stock or out of stock: go to question 5
   - Unavailable: go to fix C (“Unavailable” usually means no B2B price)
3. **Does the product show the same number in Product data lookup?** Product data lookup shows the stock SparkLayer has for the product. Where to look: Pricing > Products (SparkLayer).
   - Yes, it matches the storefront: go to fix A (Units committed to orders aren’t available)
   - No, it’s different: go to fix D (Wait for the product to sync)
4. **Is “Show stock availability to customers” ticked on the customer’s group?** It’s in the group’s stock display settings. Where to look: Customers > Groups (SparkLayer).
   - Yes: go to fix E (Your theme needs the stock display setting)
   - No: go to fix F (Turn on stock display for the group)
5. **Is the label in SparkLayer’s product area, or somewhere else on the page?** Your theme can show its own stock label, which SparkLayer’s settings don’t control.
   - In SparkLayer’s area: go to fix G (Check the customer’s group)
   - Somewhere else: go to fix H (That label is your theme’s)

**Fixes**

- **A. Units committed to orders aren’t available** SparkLayer shows Shopify’s Available quantity: on hand minus units committed to open orders. With 1 on hand committed to an order, 0 is available, so if the variant can be sold when out of stock it shows as pre-order. See [How the stock status is chosen](https://docs.sparklayer.io/help/storefront/stock-display.md).
- **B. Tick “Hide pre-order” on the group** Unticking “Show stock availability to customers” hides the in stock, low stock and out of stock labels only. The pre-order label has its own setting. Changes to a group apply straight away. Where: Customers > Groups (SparkLayer). See [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md).
- **C. “Unavailable” usually means no B2B price** It’s usually a price list issue, not a stock one. Next: Product missing, no B2B price or “Unavailable”?
- **D. Wait for the product to sync** SparkLayer’s stock is out of date for this product. Products refresh every 10 minutes, so check again after the next sync. If it stays wrong, check stock locations on the customer’s group and any reserved stock, then contact us. Where: Pricing > Products (SparkLayer).
- **E. Your theme needs the stock display setting** Stock messages also need SparkLayer’s theme configuration to include stock display. Tell us the theme name and we’ll add it.
- **F. Turn on stock display for the group** Tick “Show stock availability to customers” on the customer’s group and save. It applies straight away. Where: Customers > Groups (SparkLayer).
- **G. Check the customer’s group** Stock display is set per customer group, and changes apply straight away. Check you changed the group this customer is in, and that they’re signed in. Where: Customers > Groups (SparkLayer). Next: Wrong prices, payment methods or shipping for a customer?
- **H. That label is your theme’s** SparkLayer’s settings don’t control labels your theme adds. Hide it for B2B customers in your theme, or send us the page link and we’ll help.

**Why isn't stock showing to my customers?**

Check that **Show stock availability to customers** is ticked in the customer group's **Stock display** rule (or in the base customer group it inherits from), and that your Core Script is version 2.0 or later. The version is 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.

Stock messages also need SparkLayer's configuration for your theme to include the stock display setting. If no stock messages show at all, for any customer, [contact our support team](https://docs.sparklayer.io/help/support.md) and we'll check it.

**Why are the stock numbers different from my platform?**

SparkLayer shows the **available** quantity, not the quantity on hand. On Shopify, units committed to open orders aren't available, so 1 on hand and 1 committed shows as 0. See [How the status is chosen](#how-the-status-is-chosen).

If the available quantity in your platform still doesn't match, wait 10 minutes for the next product sync. Then search for the variant in **Product data lookup** at **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app. See [Product and customer sync](https://docs.sparklayer.io/help/integrations/data-sync.md#check-your-products-are-syncing).

**Why does a product show a stock label I can't turn off?**

It may come from your theme rather than SparkLayer. The settings on this page only change the labels in SparkLayer's interfaces. To remove a label your theme adds, change your theme or ask your developer.

## FAQs

**Why can retail customers buy pre-order products?**

**Shopify only:**

On Shopify, "Continue selling when out of stock" applies to all customers. To keep pre-order products for B2B customers, see [Sell pre-order products to B2B customers only](#sell-pre-order-products-to-b2b-customers-only).

**How do I show stock on a SparkLayer version before 2.0?**

Before version 2.0, stock display was set in the Core Script rather than in SparkLayer, so your developer sets it there. See [Frontend integration](https://docs.sparklayer.io/developers/frontend.md) for how to update the Core Script.

```javascript title="Core Script"
display: {
stock: {
  show: true,
  max: 50,
  last: 5,
  low: 15,
},
},
```

| Setting | What it does |
| --- | --- |
| `max` | The highest stock level shown to customers. Stock above it shows as "XX+ available". |
| `last` | Tells customers stock is down to its last items, with a red "Last stock" message. |
| `low` | Tells customers stock is low, with an orange "Low stock" message. |


---

# Quantity rules

URL: https://docs.sparklayer.io/help/storefront/quantity-rules
Applies to: Shopify, BigCommerce, WooCommerce, Magento

Control how many units B2B customers can order: set pack sizes, minimum and maximum quantities per variant or product, and order limits per customer group.

> **Quick summary**
>
> - Quantity rules control how many units of a product B2B customers can order: a **pack size** (for example, multiples of 6) or a **minimum** or **maximum** quantity.
> - The basic way: turn on SparkLayer's metafields once, then type a number into the **B2B - Pack Size** (or minimum or maximum) field on each product variant.
> - For a limit on the whole order, such as a minimum order value or number of items, use [order limits](#order-limit-rules) on a customer group instead. No metafields needed.
> - Available on every plan. Wix doesn't support metafields, so product quantity rules aren't available on Wix.

## Set a pack size

A pack size means a product must be ordered in multiples of a number, for example 6, 12, 18. With a pack size of 6, the quantity selector moves in steps of 6. It's also called a quantity increment.

**Shopify:**

1. **Turn on the pack size field (once).** In SparkLayer, 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 and, in the **Metafields** card, click **Configure** next to **SparkLayer metafields**. Make sure **B2B - Pack Size** is enabled. SparkLayer adds the field to your Shopify variants.

   **More detail**

   See [Shopify metafields and data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md). To create the field yourself instead, go to **Settings > Custom data > Variants** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data/productvariant/metafields)) in the Shopify admin and add a definition:

   | Field                 | Value                                   |
   | --------------------- | --------------------------------------- |
   | **Name**              | Any name, for example `B2B - Pack Size` |
   | **Namespace and key** | `sparklayer.pack_size`                  |
   | **Type**              | **Integer**, **One value**              |

2. **Enter the pack size.** Open the product in the Shopify admin, select a variant and enter the pack size in the **B2B - Pack Size** field, for example `6`.

3. **Save** the product.

4. **Check it.** Sign in to your store as a B2B customer and open the product. The quantity selector moves in steps of 6, and a **Qty rules apply** link under it says "This product comes in pack sizes of 6".

**Lots of products? Fill them in one table (Shopify):** in your Shopify admin, go to **Products**, tick the products and click **Edit products**. Click **Columns**, tick **B2B - Pack Size** under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

> **Common mistake: wrong namespace**
>
> If you create the field yourself, its **Namespace and key** must read exactly `sparklayer.pack_size`. Shopify fills in `custom.` for you, and SparkLayer never reads that. See [Add metafields by hand](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#add-metafields-by-hand).

**Other platforms:**

1. **Add the field.** Add a variant-level product field with the values below. See your platform's guide for where to add it: [BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce/metafields.md), [WooCommerce](https://docs.sparklayer.io/help/platforms/woocommerce/metafields.md) or [Magento](https://docs.sparklayer.io/help/platforms/magento/metafields.md).

   | Field                | Value                           |
   | -------------------- | ------------------------------- |
   | **Custom data type** | Variant-level (products)        |
   | **Metafield type**   | `integer`                       |
   | **Namespace**        | `sparklayer`                    |
   | **Key**              | `pack_size`                     |
   | **Value**            | A whole number, for example `6` |

2. **Turn it on in SparkLayer.** 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 and, in the **Metafields** card, click **Configure** next to **SparkLayer metafields**, then enable the pack size. SparkLayer doesn't read a field until it's enabled, even if it already exists in your store.

3. **Check it.** Sign in to your store as a B2B customer and open the product. The quantity selector moves in steps of your pack size.

For more detail, see the [developer docs](https://docs.sparklayer.io/developers.md).

Every quantity rule is set on the product variant, even when the product has a single variant. To give all of a product's variants the same rule, enter it on each one, or use the bulk editor.

## Set minimum and maximum quantities

Minimum and maximum quantities stop customers ordering too few or too many units. Each one has its own field, and they work the same way as the pack size:

| Rule | What it does | Field (metafield key) |
| --- | --- | --- |
| **Minimum per variant** | Each variant (for example each colour) must be ordered in at least this quantity. | `min_order_quantity` |
| **Maximum per variant** | Each variant can be ordered in at most this quantity. | `max_order_quantity` |
| **Minimum per product** | The total across all of a product's variants must be at least this quantity. | `min_order_parent_quantity` |
| **Maximum per product** | The total across all of a product's variants can be at most this quantity. | `max_order_parent_quantity` |

1. Turn on the field for your rule. On Shopify, 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 and, in the **Metafields** card, click **Configure** next to **SparkLayer metafields**. On other platforms, add it first using the [metafield reference](#metafield-reference), then enable it there.
2. On each variant, enter a whole number, for example `6`, `12` or `20`. Product-wide rules are still entered on each variant.
3. Save the product.

**Lots of products? Fill them in one table (Shopify):** in your Shopify admin, go to **Products**, tick the products and click **Edit products**. Click **Columns**, tick the SparkLayer field under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

**BigCommerce only:**

On BigCommerce, you can also use BigCommerce's own [Minimum and Maximum Order Quantity](https://support.bigcommerce.com/s/article/Minimum-Maximum-Purchase-Quantity) product setting. SparkLayer applies it to each variant, so each variant gets its own minimum or maximum, even though BigCommerce sets it on the product.

## What customers see

When a product has a quantity rule, the [product interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) apply it as customers build their order:

- The quantity selector follows the rule. If a customer types a quantity that doesn't fit the pack size, it updates to fit.
- A **Qty rules apply** link appears under the quantity selector. It opens the rule, such as "This product comes in pack sizes of 6".
- With a pack size, a pack price shows under the unit price, for example **Pack (6): US$71.40**.

### Show or hide the pack price

The pack price is the unit price multiplied by the number of items in a pack. It shows in the product detail interface.

To hide the pack price, you or your developer add this line to your [custom CSS](https://docs.sparklayer.io/help/storefront/customising-design.md):

```css
--spark-pdp-pack-size: none;
```

To change the pack price wording without code, add a translation override for the key `pdp.price.pack-size` at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app. In the text, `{packSize}` is the pack size and `{price}` the pack price.

**For developers: set the text in the Core Script**

Set it in your Core Script instead (see [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md)):

```javascript title="Core Script"
translations: {
  en: {
   "pdp.price.pack-size": "Pack ({packSize}): {price}",
  }
},
```

### Hide the "Qty rules apply" message

To hide the link, you or your developer add this line to your [custom CSS](https://docs.sparklayer.io/help/storefront/customising-design.md):

```css
--spark-product-qty-rules-display: none;
```

## Set order limits

Order limits apply to the whole order rather than to one product, and customers can't check out until their order meets them. They're rules on a [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md), so they don't need metafields. There are two:

| Rule | What it limits | Example |
| --- | --- | --- |
| **Order total limits** | The order total: a minimum and, if you want one, a maximum, per currency. | The order must be at least $250. |
| **Order quantity limits** | The number of items in the order: a minimum or a maximum. | The order must have at least 12 items. |

To set them:

1. 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 click a group's name (or **Edit** on the base customer group, for every group).
2. Under **Inherited rules**, click **+ Override** next to **Order total limits** or **Order quantity limits** (on the base group, **+ Customize**).
3. For **Order total limits**, choose a **Currency** and enter a **Minimum order total** and, if you want one, a **Maximum (optional)**. To set a limit in another currency, click **Add order total limit**. To remove one, click the bin icon next to it. For **Order quantity limits**, click **Configure**.
4. Click **Save**.

**More detail**

- Order totals are **net**, which means they exclude tax. With [tax-inclusive price display](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-tax-inclusive-prices) on, they're checked against the gross total the customer sees instead.
- You can also enter a minimum order value when you [create a customer group](https://docs.sparklayer.io/help/customers/customer-groups.md#create-a-customer-group). It becomes the group's **Order total limits** rule.
- Groups follow the base customer group's limits until you override them. Click **Reset** on the rule to hand it back.
- For a minimum, maximum or pack size on one product, use the [product quantity rules](#set-minimum-and-maximum-quantities) above instead.

When a customer's order doesn't meet a limit, the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) shows a message such as "Your order must be more than $100 to meet the order requirements" and **Checkout** is unavailable until they change their order.

### Change the order limit messages

To change the wording without code, add a translation override for the message's key, shown below, at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app. See [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md). In the text, `{amount}` is the order total limit, and `{minimum}` and `{maximum}` the number of items.

**For developers: set the text in the Core Script**

For order total limits:

```javascript title="Core Script"
translations: {
  en: {
    "cart.validation-message.minimum-order-totals": "Your order must be more than {amount} to meet the order requirements.",
    "cart.validation-message.maximum-order-totals": "Your order must be less than {amount} to meet the order requirements.",
  }
},
```

For order quantity limits:

```javascript title="Core Script"
translations: {
  en: {
    "cart.validation-message.minimum-order-item-quantity": "Your order must have at least {minimum} items to meet the order requirements.",
    "cart.validation-message.maximum-order-item-quantity": "Your order must not exceed {maximum} items to meet the order requirements.",
  }
},
```

## Quantity pricing (tiered pricing)

Quantity pricing gives lower unit prices for larger quantities, for example buy 1 for $10 or 10 for $8. See [Quantity pricing and settings](https://docs.sparklayer.io/help/pricing/quantity-pricing.md).

Quantity pricing sets a minimum too: the lowest quantity tier in the customer's price list is the smallest quantity they can order. If a product's first tier is 50+, customers see "Unavailable in selected quantity" below 50. To let them order fewer, add a price from a quantity of 1.

## Unit of measure pricing

Unit of measure pricing sets prices for units such as boxes, cartons or pallets. See [unit of measure pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md#set-up-unit-of-measure-pricing).

## Set different rules for each customer group

Everything above applies to all your B2B customers. To give a customer group its own pack size, minimum or maximum, use the `sparklayer.settings` field on the variant ([product settings](https://docs.sparklayer.io/help/storefront/product-settings.md)). For example, most customers could buy in packs of 6 and a `tier-2` group in packs of 12.

1. Find each group's handle: open the group at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app and look under **Handle (or ID)**.
2. In the form below, enter each group's handle and its rules. It writes the value for you. Use `base` for the rules everyone else gets.
3. Click **Copy**, paste the value into the variant's `sparklayer.settings` field and save. To give many variants the same rules, paste it into each row in Shopify's bulk editor.

**Field details, if you add the field by hand**

| Field | Value |
| --- | --- |
| **Custom data type** | Variants ([Shopify](https://admin.shopify.com/settings/custom_data/productvariant/metafields)), or variant-level product fields on other platforms |
| **Metafield type** | `JSON` |
| **Namespace** | `sparklayer` |
| **Key** | `settings` |
| **Value** | One entry per customer group, for example `[{"customer_group":"base","pack_size":6},{"customer_group":"tier-2","pack_size":12}]` |

See [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md) for everything this field can do.

> **Once a variant has settings, its other quantity fields are ignored**
>
> If a variant has any `sparklayer.settings` value, even one that only hides it from a group, SparkLayer ignores its individual fields such as `sparklayer.pack_size`. Put the pack size, minimum and maximum inside the JSON instead.

### Which rule wins

SparkLayer uses the first of these that applies to the customer:

1. **The customer's group entry in `sparklayer.settings`.** It overrides the `base` entry for that group.
2. **The `base` entry in `sparklayer.settings`.** It's the default for every customer group.
3. **The individual fields**, such as `sparklayer.pack_size` and `sparklayer.max_order_quantity`, but only when the variant has no `sparklayer.settings` value.

For example:

```json
[
  { "customer_group": "base", "pack_size": 50 },
  { "customer_group": "retail-partners", "pack_size": 10, "display": true },
  { "customer_group": "distributors", "display": false }
]
```

Every group buys in packs of 50, except `retail-partners`, who buy in packs of 10. `distributors` don't see the product. A `sparklayer.pack_size` on the same variant is ignored. See [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md#which-rule-wins).

## Metafield reference

This reference is for whoever sets up your product data. All keys use the namespace `sparklayer` and are set on product variants. On Shopify, the custom data type is [Variants](https://admin.shopify.com/settings/custom_data/productvariant/metafields). On other platforms, use variant-level product fields.

| Key | Type | Value |
| --- | --- | --- |
| `pack_size` | `integer` | A whole number, for example `6` |
| `min_order_quantity` | `integer` | A whole number, for example `6`, `12` or `20` |
| `min_order_parent_quantity` | `integer` | A whole number, for example `6`, `12` or `20` |
| `max_order_quantity` | `integer` | A whole number, for example `6`, `12` or `20` |
| `max_order_parent_quantity` | `integer` | A whole number, for example `6`, `12` or `20` |
| `settings` | `JSON` | One entry per customer group. See [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md). |

## Troubleshooting

**Diagnose: Pack sizes or quantity limits not applying?** Check the metafields behind your product rules.

1. **Are SparkLayer’s metafields turned on in SparkLayer?** SparkLayer doesn’t read metafields until they’re configured in the Metafields card. Where to look: Integrations > Platform (SparkLayer).
   - Yes: go to question 2
   - No / not sure: go to fix A (Turn on SparkLayer’s metafields)
2. **How is the rule set up on the product?** Single metafields, such as `sparklayer.pack_size`, set one rule for everyone. The `sparklayer.settings` metafield sets rules per customer group. Where to look: Products > select a variant > Metafields (Shopify admin).
   - Single metafields: go to question 3
   - The sparklayer.settings metafield: go to question 4
   - Not sure: go to question 3
3. **Does the variant also have a `sparklayer.settings` metafield with a value?** When it does, it takes priority over the single metafields. Where to look: Products > select a variant > Metafields (Shopify admin).
   - Yes: go to fix B (Put the rule inside the settings metafield)
   - No: go to question 5
4. **Does the JSON have an entry for this customer’s group, or a `base` entry?** `base` is the default for every group. An entry for a group overrides it. Use the group’s handle, for example `vip`. Where to look: Customers > Groups (SparkLayer).
   - Yes: go to question 6
   - No: go to fix C (Add an entry for the group)
5. **Is the metafield set on the variant, not the product?** Rules are read per variant, even when a product has only one variant. Where to look: Settings > Custom data > Variants (Shopify admin).
   - Yes, on the variant: go to question 7
   - No, on the product: go to fix D (Move the metafield to the variant)
6. **Is the JSON correctly formatted, with straight quotes?** A missing quote, comma or bracket breaks every rule in the value. Paste it into a JSON checker if unsure.
   - Yes: go to question 8
   - No / not sure: go to fix E (Fix the JSON)
7. **Does the definition’s namespace and key read exactly as documented, such as `sparklayer.pack_size`?** In Shopify the namespace and key are one field. Any other spelling is ignored. Where to look: Settings > Custom data > Variants (Shopify admin).
   - Yes: go to question 9
   - No / not sure: go to fix F (Correct the metafield definition)
8. **Does the rule work on other products, just not this one?** Products on a different theme template may not have SparkLayer’s product widget.
   - Yes: go to fix G (Add SparkLayer to this product’s template)
   - No, it doesn’t work anywhere: go to question 10
9. **Does this variant have a whole number entered?** An empty value means no rule. Where to look: Products > select a variant > Metafields (Shopify admin).
   - Yes: go to question 8
   - No: go to fix H (Add a value to the variant)
10. **Are you testing as a signed-in customer in the group you expect?** Rules follow the customer’s group.
   - Yes: go to fix I (Everything checks out)
   - No / not sure: go to fix J (Check the customer’s group)

**Fixes**

- **A. Turn on SparkLayer’s metafields** In the Metafields card, click Configure and enable the metafields you use. SparkLayer adds their definitions to Shopify for you. Where: Integrations > Platform (SparkLayer). See [Shopify metafields](https://docs.sparklayer.io/help/platforms/shopify/metafields.md).
- **B. Put the rule inside the settings metafield** When a variant has `sparklayer.settings`, its JSON takes priority and the single metafields are ignored. Add the rule, such as `pack_size`, to each group’s entry in the JSON. Where: Products > select a variant > Metafields (Shopify admin). See [Which rule wins](https://docs.sparklayer.io/help/storefront/quantity-rules.md).
- **C. Add an entry for the group** Add an entry with the group’s handle and its rule, or a `base` entry to set a default for everyone. Where: Products > select a variant > Metafields (Shopify admin). See [Product settings](https://docs.sparklayer.io/help/storefront/product-settings.md).
- **D. Move the metafield to the variant** Create the definition under Variants, then add the value to each variant. Where: Settings > Custom data > Variants (Shopify admin).
- **E. Fix the JSON** Correct the formatting and save. Copy an example from Quantity rules as a starting point. See [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md).
- **F. Correct the metafield definition** Use the exact namespace and key from Quantity rules, such as `sparklayer.pack_size` with the Integer type. A definition under another namespace is ignored. Where: Settings > Custom data > Variants (Shopify admin). See [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md).
- **G. Add SparkLayer to this product’s template** The product uses a template without SparkLayer’s product widget, so its rules can’t show. Switch it to your main template, or send us the template name and we’ll add the widget. Where: Products > select the product (Shopify admin).
- **H. Add a value to the variant** Enter a whole number, for example 6, and save. Each variant needs its own value. Where: Products > select a variant > Metafields (Shopify admin).
- **I. Everything checks out** Your setup looks right, so we'll take it from here. Send us your answers with the product link and the customer’s email.
- **J. Check the customer’s group** Rules depend on the customer’s group, so a missing or wrong group tag stops them applying. Next: Wrong prices, payment methods or shipping for a customer?

## FAQs

**What happens if a customer enters a quantity that doesn't fit the pack size?**

The quantity updates to fit the pack size. Products added with a [1-click ordering button](https://docs.sparklayer.io/help/storefront/product-display.md#add-1-click-ordering-buttons-spark-buttons) are rounded up to the next full pack.

**Can customers add a set of products in one click?**

Yes. Spark Buttons add a set of SKUs and quantities to an order in one click. See [1-click ordering buttons](https://docs.sparklayer.io/help/storefront/product-display.md#add-1-click-ordering-buttons-spark-buttons).

**Can I change the quantity rule messages?**

Yes. The messages are translations such as `global.product-settings.pack-size` and `min-order-quantity`. See [Change text that contains variables](https://docs.sparklayer.io/help/storefront/languages-and-international.md#change-text-that-contains-variables).


---

# Languages and international

URL: https://docs.sparklayer.io/help/storefront/languages-and-international

Show SparkLayer in 28 languages, translate Shopify product data, set a locale for date and currency formats, and change any text in the B2B interfaces.

> **Quick summary**
>
> - You can change any text in SparkLayer's [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md), such as a button label or a heading, without code at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app. See [Change SparkLayer's text](#change-sparklayers-text).
> - Customers see the interfaces in your store's language automatically, from 28 supported languages. Your developer can set a different language in the [Core Script](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting), the SparkLayer code in your theme.
> - Customers see dates and currency symbols in their own browser's regional format, unless you set a fixed locale.
> - Showing translated product data is available on Shopify only, and our team needs to turn it on.

## How it works

Every piece of text customers see in SparkLayer's interfaces has a name, called a key. For example, `pdp.table.price` is the **Price** column heading on product pages. SparkLayer shows the text for each key in the customer's language.

To change the wording, you give a key your own text for a language. This is called a translation override, even when you're only rewording English.

Some strings include variables in curly brackets, such as `{packSize}` or `{price}`, which SparkLayer fills in when it shows the text.

## Change SparkLayer's text

You can change any piece of SparkLayer's text, in any supported language. Most changes need no code: find the key for the text, then add your own wording at **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app.

### Find the key for a piece of text

To find a key, turn on translation keys. Your store then shows each key in place of its text. For example, the product page's **Price** column shows as `pdp.table.price` and the add button as `pdp.add-to-order.text`.

To turn them on without code, go to **Storefront > Options > Translation overrides** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Translation overrides** in the Shopify app and turn on **Show translation keys**. Or your developer adds this setting to your Core Script:

```javascript title="Core Script"
showTranslations: true,
```

Signed-in B2B customers see the keys too, so turn this on only briefly, or on an unpublished theme.

### Change text without code

Once you know the key, add your own wording in Storefront options:

1. Go to **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app and open **Translation overrides**.
2. Click **Add override**.
3. Choose your store's language, for example `da` for a Danish store (see [supported languages](#supported-languages)), then the key you want to change, for example `pdp.table.price`, and enter your text, such as `Pris`.
4. Click **Save and publish**.

An override only applies to the language you choose. On a Danish store, an override for `en` never shows: use `da`. If your store has several languages, add an override for each one.

See [Storefront options](https://docs.sparklayer.io/help/storefront/storefront-options.md#translation-overrides) for more.

### Change text that contains variables

Some of SparkLayer's text includes variables, such as a pack size or a price. Variables are written in camel case inside curly brackets, for example `{packSize}`. Keep the variable in your new text where you want the value to appear.

For example, `"global.product-settings.pack-size": "This product comes in pack sizes of {packSize}"` shows customers "This product comes in pack sizes of 6".

You can use these keys in Storefront options as well as in the Core Script.

**Keys that contain variables, with their default English text**

```javascript title="Core Script"
<script>
  window.sparkOptions = {
translations: {
  en: {

    // Global
    "global.per-unit": "{price} per unit",
    "global.product-settings.pack-size": "This product comes in pack sizes of {packSize}",
    "min-order-quantity": "Each variant has a minimum order quantity of {minOrderQuantity}",
    "max-order-quantity": "Each variant has a maximum order quantity of {maxOrderQuantity}",
    "min-order-parent-quantity": "This product has a minimum quantity of {minOrderParentQuantity} across all variants",
    "max-order-parent-quantity": "This product has a maximum quantity of {maxOrderParentQuantity} across all variants",

    // Products
    "pdp.setting-info.pack-size": "This product comes in pack sizes of {packSize}",
    "pdp.price.pack-size": "Pack ({packSize}): {price}",
    "pdp.messaging.back-order-due": "Due: {restockDate}",
    "pdp.messaging.stock-qty.low-stock": "Only {qty} available",
    "pdp.messaging.stock-qty.last-stock": "Last {qty} available",
    "pdp.messaging.stock-qty.in-stock": "{qty} available",
    "product-card.price-breaks.cheapest": "From {price} for {qty}+",
    "product-card.price-breaks.saving": "(Save {per}%)",
    "product-card.messaging.back-order-due": "Due: {restockDate}",

    // My Order
    "cart.no-of-order-lines": "{numberOf} {numberOf, plural, =1 {line} other {lines}}",
    "cart.no-of-order-items": "{numberOf} {numberOf, plural, =1 {item} other {items}}",
    "cart.validation-messages.minimum-order-totals": "Your order must be more than {amount} to meet the order requirements.",
    "cart.validation-messages.maximum-order-totals": "Your order must be less than {amount} to meet the order requirements.",
    "cart.validation-messages.minimum-parent-quantity": "Please note, {productName} has a minimum order quantity of {minimum}.",
    "cart.validation-messages.maximum-parent-quantity": "Please note, {productName} has a maximum order quantity of {maximum}.",
    "cart.validation-messages.out-of-stock": "Sorry, {sku} is now unavailable. Please remove this product from your order before checkout",
    "cart.validation-messages.limited-stock-available": "Sorry, we only have {qty} of {sku} available right now, please adjust the quantity in your order before checkout",
    "cart.checkout.confirm-btn.complete": "Complete Order: {total}",
    "cart.checkout.confirm-btn.checkout": "Complete Payment: {total}",
    "cart.checkout.confirm-btn.quote": "Submit Quote: {total}",
    "cart.thanks.payment.blurb": "Your order has now been placed and you will shortly receive email confirmation to {email}. You can check the status of your order at any time by going to 'My Account'.",

    // My Account
    "account.main.my-details.payment-on-account.detail": "Your account balance is {balance} with a credit limit of {creditLimit}.",
    "account.main.my-details.payment-on-account.detail-without-limit": "Your account balance is {balance}.",
  }
},
   },
  };
</script>
```

### Change text in the Core Script (for developers)

Instead of Storefront options, your developer can set text with `translations` in the Core Script.

**Shopify:**

Add this to your theme's `theme.liquid` file, just before the closing `</head>` tag, with the keys and text you want:

```html
<script>
  window.sparkOptions = {
    translations: {
       en: {
         "pdp.table.price": "Price",
       }
    },
  };
</script>
```

On a store in another language, use that language's code. For example, on a Danish store:

```html
<script>
  window.sparkOptions = {
    translations: {
       da: {
         "pdp.table.price": "Pris",
       }
    },
  };
</script>
```

**Other platforms:**

Add the `translations` setting to the [SparkLayer Core Script](https://docs.sparklayer.io/developers/frontend.md) in your website's header, inside the `<head>` tags. On BigCommerce, this is usually in `/templates/layout/base.html`.

Your Core Script is the code you added to your site's header when you installed SparkLayer (see your platform's install guide). It loads SparkLayer with a script tag like this:

```html
<script async src="https://sparkcdn.io/sparkjs/yourstorehere/live"></script>
```

New installs use the latest version. To pin a version or move to the latest, go to **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, choose a **Version for this store** and click **Save version**. See [What's new](https://docs.sparklayer.io/help/whats-new.md) for changes in each version.

#### What's in the Core Script

The Core Script tells SparkLayer how to work on your website. A full example:

```html
<!-- SparkLayer Core Script: see the frontend integration guide in the developer docs -->

<script>
  window.sparkOptions = {
    siteId: "examplestore", // your unique site id
    platform: "shopify", // your platform
    rootUrl: {{ routes.root_url | json }},
    language: {{ request.locale.iso_code | json }},
    accountRedirect: {
      urlRegex: /\/account/g,
      goTo: "/index", // page to redirect logged in users to
    },
    display: {
      stock: {
        show: false, // set to true to show stock level display
        max: 50, // highest stock level to show
        last: 5, // last remaining stock
        low: 15, // low stock threshold
        last: true, // set to false to hide last stock message
      },
    },
    auth: {
      user: {{ customer.email | json }},
      token: {{ customer.metafields.sparklayer.authentication | json }},
    },
  };
</script>
<script async src="https://sparkcdn.io/sparkjs/yourstorehere/live"></script>
```

| Setting | What it does |
| --- | --- |
| `siteId` | Your site's unique identifier. See [Account settings](https://docs.sparklayer.io/help/dashboard/account.md). |
| `platform` | Your eCommerce platform. |
| `language` | The language to use. |
| `accountRedirect` | The URL to send signed-in customers to. |
| `display` | Which display settings to turn on. See [Storefront](https://docs.sparklayer.io/help/storefront.md). |
| `auth` | The signed-in customer's authentication details. |

When you add text in the Core Script, check:

- **The language code:** replace `en` with your store's language code (see [supported languages](#supported-languages)).
- **A comma at the end of every line** of text.

## Find and fix untranslated text

If some of SparkLayer's text still shows in English on a store in another language, find each piece and give it your own wording:

1. Turn on translation keys, ideally on an unpublished theme. See [Find the key for a piece of text](#find-the-key-for-a-piece-of-text).
2. Sign in to your store as a B2B customer and go through every screen: product pages, collection pages, the cart and each checkout step, and **My Account**. If you use [sales agents](https://docs.sparklayer.io/help/sales-reps.md), sign in as one and check **My Customers** and the **Order builder** too.
3. Note the key of each piece of text that's still in English.
4. Add an override for each key in your store's language (for example `da`, not `en`). See [Change text without code](#change-text-without-code).
5. Turn translation keys off again.

If a piece of text shows no key, or stays in English after you've added an override in the right language, the translation may be missing on our side. [Contact our support team](https://docs.sparklayer.io/help/support.md) with the page, a screenshot and your store's language.

SparkLayer forms aren't translated this way: see [Translate a form](https://docs.sparklayer.io/help/forms/embedding-and-styling.md#translate-a-form). Product names and options come from your store: see [Show translated product data](#show-translated-product-data-shopify).

## Supported languages

When a customer signs in, they see SparkLayer in your store's language. SparkLayer supports these 28 languages:

| Code | Language |
| --- | --- |
| `en` | English (default) |
| `ar` | Arabic (with full right-to-left support) |
| `zh` | Chinese |
| `hr` | Croatian |
| `cs` | Czech |
| `da` | Danish |
| `nl` | Dutch |
| `fi` | Finnish |
| `fr` | French |
| `de` | German |
| `el` | Greek |
| `he` | Hebrew (with full right-to-left support) |
| `hu` | Hungarian |
| `is` | Icelandic |
| `it` | Italian |
| `ja` | Japanese |
| `lt` | Lithuanian |
| `lv` | Latvian |
| `no` | Norwegian |
| `pl` | Polish |
| `pt` | Portuguese |
| `ro` | Romanian |
| `ru` | Russian |
| `sk` | Slovak |
| `sl` | Slovenian |
| `es` | Spanish |
| `sv` | Swedish |
| `th` | Thai |

If you need a language that isn't listed, [contact us](https://docs.sparklayer.io/help/support.md) and we'll explain how to supply translations.

## Set the storefront language

SparkLayer detects your store's language automatically, so most stores don't need to change anything. On Shopify, the widgets follow the language the customer is browsing your store in (Shopify's locale), not their browser's language: a customer on your French storefront sees SparkLayer in French. This change is for your developer. To use a different language, your developer changes the `language` value in your Core Script to one of the codes above, for example `fr`:

```javascript title="Core Script"
/* Modify the below code with the language variable above, e.g. fr*/
language: {{ request.locale.iso_code | json }},
/* End of code */
```

## Show translated product data (Shopify)

**Shopify only:**

SparkLayer can show customers product data, such as product names and options, in their own language, from your Shopify translations. This is available on Shopify only and isn't on by default: our team turns it on for you. Step 3 is a code change for your developer.

1. In Shopify, add your translations, assign the languages to your Shopify markets and publish the languages.

2. Check your SparkLayer Core Script is version 3.13 or later: see **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.

3. In your Shopify theme's `theme.liquid`, set the `language` option in the Core Script to:

   ```javascript title="Core Script"
   language: "{{ localization.language.iso_code }}-{{ localization.country.iso_code }}",
   ```

4. [Contact us](https://docs.sparklayer.io/help/support.md) to turn on product translations. Tell us your store and its languages.

Once it's set up, product data in SparkLayer matches the rest of your site, based on the languages you've set up in Shopify and assigned to markets.

If product names still show in your default language, check:

- **The translations are published** in Shopify, not just saved.
- **Each language is assigned to a Shopify market.**
- **Your Core Script is version 3.13 or later.**
- **The `language` setting matches the locale**, as in step 3.

## Set a locale for dates and currency

By default, customers see dates and currency symbols in the locale (regional format) of their own browser, so they match their regional settings. To use the same format for every customer, your developer sets a fixed `locale` in your Core Script:

```javascript title="Core Script"
/* Modify the below code with the locale required e.g. en-AU*/
locale: 'en-AU',
/* End of code */
```

The locale is a language code and a 2-letter country code joined by a hyphen, for example:

| Locale | Formats for |
| --- | --- |
| `'en-GB'` | British English |
| `'en-US'` | American English |
| `'en-AU'` | Australian English |
| `'de-DE'` | German |

When you set a locale, currency prefixes on your B2B prices follow it. For example, with `locale: 'en-US',` a price shown as **US$4.00** shows as **$4.00**. The locale only changes how prices are formatted, not their values.

## FAQs

**Can I support a language that isn't listed?**

[Contact us](https://docs.sparklayer.io/help/support.md) and we'll send details on how to supply translations.

**Why isn't my text change showing?**

Check that you used your store's language code from [supported languages](#supported-languages) (for example `da` on a Danish store, not `en`), that every line ends with a comma, and, if you used Storefront options, that you clicked **Save and publish**. If it still doesn't show, see [Find and fix untranslated text](#find-and-fix-untranslated-text).

**Can I translate a SparkLayer form?**

Yes, by making one copy of the form per language. Forms aren't covered by the Core Script's translations. See [Translate a form](https://docs.sparklayer.io/help/forms/embedding-and-styling.md#translate-a-form).

**Does setting a locale convert prices into another currency?**

No. The locale only changes how prices and dates are formatted. Prices come from the customer's [price list](https://docs.sparklayer.io/help/pricing/managing-pricing.md).


---

# Product rules per customer group

URL: https://docs.sparklayer.io/help/storefront/product-settings
Applies to: Shopify, BigCommerce, WooCommerce, Magento

Give customer groups their own pack sizes, quantity limits, reserved stock and product visibility with the sparklayer.settings metafield on each variant.

> **Quick summary**
>
> - Product settings give one [customer group](https://docs.sparklayer.io/help/glossary.md#customer-group) its own rules for a product. Customers in that group can get a different pack size, minimum or maximum quantity, or reserved stock. You can also hide a product from the group, or stop them ordering it.
> - You set them in a field on each product variant in your platform's admin, called the `sparklayer.settings` [metafield](https://docs.sparklayer.io/help/glossary.md#metafields). The [form on this page](#set-product-settings-for-a-customer-group) writes its value for you to copy. To hide products, see [Hide products from customers](https://docs.sparklayer.io/help/guides/hide-products.md).
> - For a rule that applies to all B2B customers, use the simpler single-value fields in [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md) and [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md#reserving-stock) instead.
> - Available on every plan, on Shopify, BigCommerce, WooCommerce and Magento. Wix doesn't support metafields, so these settings aren't available on Wix.

## How it works

Customers in each group see the product with their group's rules, for example a pack size of 50 instead of 1 in the quantity selector.

Behind this is a metafield: an extra field on a product or variant in your eCommerce platform's admin. SparkLayer reads the `sparklayer.settings` metafield on each product variant. Its value is a list with one entry per customer group. Each entry names the group and the settings that apply to it:

```javascript
[
    {
        "customer_group": "gold-tier",
        "min_order_quantity": 5,
        "max_order_quantity": 50
    }
]
```

The `base` entry is the default for every customer group. An entry for a specific group, such as `influencer`, overrides it for that group. You only need to include the settings you want to set. See [Which rule wins](#which-rule-wins).

To set a rule for all customers without customer groups, you can use the individual metafields instead, such as `sparklayer.pack_size` in [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md) or `sparklayer.reserve_stock_quantity` in [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md#reserving-stock). Don't combine the two on one variant: when a variant has a `sparklayer.settings` value, it takes priority over the individual metafields.

> **Before you start: turn the metafield on in SparkLayer**
>
> SparkLayer doesn't read a metafield until it's enabled in SparkLayer. 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 and, in the **Metafields** card, click **Configure** next to **SparkLayer metafields**, then enable the product settings metafield. If you create the definition yourself in Shopify, it must read exactly `sparklayer.settings`, with the type **JSON**, on **Variants**. See [Common mistake: wrong namespace](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#add-metafields-by-hand).

## Which rule wins

When SparkLayer works out a customer's rules for a variant, it checks in this order:

1. **The customer's group entry** in `sparklayer.settings`, if there is one. Its settings override the `base` entry.
2. **The `base` entry** in `sparklayer.settings`. It's the default for every customer group, including groups that have no entry of their own.
3. **The individual metafields**, such as `sparklayer.pack_size` or `sparklayer.max_order_quantity`, but only when the variant has no `sparklayer.settings` value at all.

So if you use `sparklayer.settings` to hide a product from one group, and you also want a pack size or a maximum quantity, put those keys in the JSON too, inside each group's entry. Don't rely on the individual metafields for them.

For example, this value on a variant:

```json
[
  { "customer_group": "base", "pack_size": 50 },
  { "customer_group": "retail-partners", "pack_size": 10, "display": true },
  { "customer_group": "distributors", "display": false }
]
```

| Customer group | What its customers get |
| --- | --- |
| **Base**, and every group with no entry of its own | The product, in packs of 50 |
| `retail-partners` | The product, in packs of 10 |
| `distributors` | The product is hidden |

If the same variant also had `sparklayer.pack_size` set to `6`, nobody would see packs of 6: the `sparklayer.settings` value wins.

Quantity pricing can set a minimum too. The lowest quantity tier in the customer's price list is the smallest quantity they can order. If the first tier is 50+, customers can't order fewer than 50 and may see "Unavailable in selected quantity". Add a tier from 1 to fix it. See [Quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md).

## What hides what

`display: false` in `sparklayer.settings` hides a product inside SparkLayer's own views, including [Catalog and Quick Order](https://docs.sparklayer.io/help/sales-ordering/catalog.md#hide-products). Hiding it from your Shopify theme's pages needs the free [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md) app as well. For the whole job, step by step, see [Hide products from customers](https://docs.sparklayer.io/help/guides/hide-products.md).

**Variant rules don't hide anything from retail shoppers.** `sparklayer.settings` rules only apply to signed-in B2B customers, by customer group. Retail shoppers and signed-out visitors see every variant your theme shows, and Shopify can't hide a single variant of a product from them. To keep one variant for B2B customers only, such as a 12-pack case, make it a separate product. On Shopify, tag that product `b2b-only` with B2B Catalogs.

**Shopify only:**

| What you use | SparkLayer's views (search, quick order, quick buy, cart) | Collection and search pages | Product page | Featured sections |
| --- | --- | --- | --- | --- |
| `display: false` in `sparklayer.settings` | Hidden | Still shown | Still opens. SparkLayer's product interface leaves the variant out | Still shown |
| `b2b-only` or `b2c-only` product tag, with B2B Catalogs | Not hidden | Hidden | Access denied page | Hidden |
| [Catalogs per customer group](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-advanced-catalogs.md): `display: false` for a group, with B2B Catalogs | Hidden | Hidden | Access denied page | Hidden |

**Things to check when a product isn't hidden**

- **B2B Catalogs must be enabled on your live theme.** The `b2b-only` and `b2c-only` tags only work when the app is installed and enabled on your published theme. See [Enable or disable it on other themes](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md#enable-or-disable-it-on-other-themes).
- **After an app update or a theme change**, if `b2b-only` products appear in a section such as a featured collection, disable B2B Catalogs on the live theme and enable it again. Disabling removes your changes to the access denied page, so keep a copy first.
- **The JSON uses straight quotes** (`"`). Curly quotes (“ ”), which word processors add, stop the value working. Build it with the [form](#set-product-settings-for-a-customer-group) to be safe.
- **A whole collection can't be hidden.** B2B Catalogs hides products, not collections. A third-party Shopify app can restrict who can open a collection's URL.
- **Collection pages, search and filter counts.** Hiding happens in your theme as the page loads, so a hidden product can still take a place in a collection grid and count towards product and filter totals. See [Collection grids, search and filter counts](https://docs.sparklayer.io/help/storefront/b2b-catalogs/limitations.md#grids-search-and-filter-counts).

To show a product to everyone but its price only to some customers ("price on application"), see [Price on application](https://docs.sparklayer.io/help/pricing/managing-pricing.md#price-on-application).

### Example: a product range for each customer group

A supplier sells to retail shoppers, salons and stockists from one Shopify store. Salons should see the professional range, stockists the retail-pack range, and retail shoppers neither.

1. Tag every product in both ranges `b2b-only`, so retail shoppers and signed-out visitors don't see them.

2. On each variant in the professional range, set `sparklayer.settings` to show it only to the `salons` group:

   ```json
   [
     { "customer_group": "base", "display": false },
     { "customer_group": "salons", "display": true }
   ]
   ```

3. On each variant in the retail-pack range, do the same for the `stockists` group:

   ```json
   [
     { "customer_group": "base", "display": false },
     { "customer_group": "stockists", "display": true }
   ]
   ```

| Who | Professional range | Retail-pack range | Everything else |
| --- | --- | --- | --- |
| Retail shoppers and signed-out visitors | Hidden (`b2b-only`) | Hidden (`b2b-only`) | Shown |
| Customers tagged `b2b-salons` | Shown | Hidden | Shown |
| Customers tagged `b2b-stockists` | Hidden | Shown | Shown |
| Any other B2B customer | Hidden | Hidden | Shown |

Rules are per customer group, not per customer. To give one customer their own range, put them in a group of their own. Build each value with the [form](#set-product-settings-for-a-customer-group), which also shows how to fill in many variants at once.

## Set product settings for a customer group

**Step 1.** **Create the metafield definition**

You only do this once. It adds the `sparklayer.settings` field to every variant.

- **Shopify:** in SparkLayer, 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 and, in the **Metafields** card, click **Configure** next to **SparkLayer metafields**. SparkLayer adds its metafields for you.
- **Other platforms:** follow your platform's guide: [BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce/metafields.md), [WooCommerce](https://docs.sparklayer.io/help/platforms/woocommerce/metafields.md) or [Magento](https://docs.sparklayer.io/help/platforms/magento/metafields.md).

**More detail**

**Shopify only:**

On Shopify, you can also create the definition yourself at **Settings > Custom data > Variants** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data/productvariant/metafields)), using the values in the [metafield reference](#metafield-reference).

**Step 2.** **Find the customer group's handle**

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, click the group's name and find its **Handle (or ID)**, for example `base` for the base customer group or `vip` for a group with the handle `vip`. The group's Shopify tag is `b2b-` followed by the handle. In the metafield, always write it in lowercase. See [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md#create-a-customer-group) for how handles work.

**Step 3.** **Build the value and add it to the variant**

Fill in the form below: one entry per customer group, with only the settings you want. It writes the value for you. Click **Copy**, then open the product variant in your platform's admin, paste the value into the `sparklayer.settings` field and save the variant.

**Lots of products? Fill them in one table (Shopify):** in your Shopify admin, go to **Products**, tick the products and click **Edit products**. Click **Columns**, tick the SparkLayer field under **Metafields**, type the values and click **Save**. See [Shopify's guide](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

## Examples

### Exclusive products for one group

Company X has 2 customer groups:

1. **Base**: standard B2B customers
2. **Gold tier**: preferred customers with discounted pricing and access to exclusive products

To make a range exclusive to Gold tier, they add this to the exclusive variants:

```javascript
[
    {
        "customer_group": "base",
        "display": false,
        "sell": false
    },
    {
        "customer_group": "gold-tier",
        "display": true,
        "sell": true
    }
]
```

The `base` entry hides the variants from every group, and the `gold-tier` entry overrides it, so these variants are now only visible to Gold tier customers. Variants with no `sparklayer.settings` value stay visible to everyone, so the rest of the catalogue needs nothing.

### Different pack sizes for each group

Company X has 2 customer groups:

1. **Wholesale**: other businesses that stock their products, who order large quantities
2. **Influencer**: people who promote their products on social media, who only need single units

To sell in packs of 50 to wholesale customers and singly to influencers, they use:

```text
[
    {
        "customer_group":"base",
        "pack_size":50
    },
    {
        "customer_group":"influencer",
        "pack_size":1
    }
]
```

The `base` entry applies to all customer groups. The second entry gives the `influencer` group a pack size of 1.

## Available product settings

You can set any of these for a customer group:

| Setting | Type | What it does | Default |
| --- | --- | --- | --- |
| `customer_group` | `string` | The customer group the settings apply to. Required in every entry. | |
| `pack_size` | `integer or null` | Only allow the product to be bought in multiples of this number. | `1` |
| `reserve_stock_quantity` | `integer or null` | Always keep this much stock back, usually so retail (DTC) customers can still buy it. | `null` |
| `min_order_quantity` | `integer or null` | Only allow the product to be bought in at least this quantity. | `null` |
| `max_order_quantity` | `integer or null` | Only allow the product to be bought in at most this quantity. | `null` |
| `min_order_parent_quantity` | `integer or null` | Minimum quantity across all of the product's variants. | `null` |
| `max_order_parent_quantity` | `integer or null` | Maximum quantity across all of the product's variants. | `null` |
| `display` | `boolean or null` | Whether the product shows in the frontend interfaces. | `null` |
| `sell` | `boolean or null` | Whether the product can be added to the cart. | `null` |

## Metafield reference

Use these values if you create the metafield definition yourself:

| Field | Value |
| --- | --- |
| **Custom data type** | Variants ([Shopify](https://admin.shopify.com/settings/custom_data/productvariant/metafields)) |
| **Metafield type** | `JSON` |
| **Namespace** | `sparklayer` |
| **Key** | `settings` |
| **Value** | A list of entries, for example:<br />`[{"customer_group": "base","pack_size": 1,"reserve_stock_quantity": 10,"min_order_quantity": 5,"max_order_quantity": 50,"min_order_parent_quantity": 5,"max_order_parent_quantity": 50,"display": true,"sell": true}]` |

## Troubleshooting

**Diagnose: Product showing to the wrong customers?** Check which tool should hide it.

1. **What’s happening?** Pick the closest match.
   - A product shows to customers who shouldn’t see it: go to question 2
   - A product is hidden from customers who should see it: go to fix A (Check the product itself)
2. **Where do they see it?** SparkLayer’s own views and your theme’s pages are hidden by different tools.
   - In SparkLayer’s quick order, search or cart: go to question 3
   - On collection, product or search pages: go to question 4
   - In a section such as a featured collection: go to question 5
3. **Does the variant’s `sparklayer.settings` metafield set `"display": false` for the customer’s group?** Use the group’s handle, for example `base`. Entries for a group override the `base` entry. Where to look: Products > select a variant > Metafields (Shopify admin).
   - Yes: go to question 6
   - No: go to fix B (Add a rule for that group)
4. **Is the free B2B Catalogs app installed and enabled on your live theme?** The visibility metafield only hides products inside SparkLayer. Hiding them from your theme’s pages needs B2B Catalogs. Where to look: Online Store > Themes (Shopify admin).
   - Yes: go to question 7
   - No / not sure: go to fix C (Install B2B Catalogs and enable it on your live theme)
5. **Is the free B2B Catalogs app installed and enabled on your live theme?** Sections such as featured collections are your theme’s, so only B2B Catalogs can hide products in them. Where to look: Online Store > Themes (Shopify admin).
   - Yes: go to fix D (Turn B2B Catalogs off and on again on your live theme)
   - No / not sure: go to fix C (Install B2B Catalogs and enable it on your live theme)
6. **Is the JSON written with straight quotes and valid formatting?** Curly quotes from a word processor, or a missing comma or bracket, break every rule in the value. Paste it into a JSON checker if unsure.
   - Yes: go to fix E (Everything checks out)
   - No / not sure: go to fix F (Fix the JSON)
7. **Is the product tagged, for example `b2b-only`, or in a catalog for the right groups?** `b2b-only` hides a product from retail shoppers. `b2c-only` hides it from B2B customers. Where to look: Products > select the product (Shopify admin).
   - Yes: go to fix D (Turn B2B Catalogs off and on again on your live theme)
   - No: go to fix G (Tag the product)

**Fixes**

- **A. Check the product itself** A product that should show but doesn’t usually has a SKU, status, sales channel or price list issue. Next: Product missing, no B2B price or “Unavailable”?
- **B. Add a rule for that group** Add an entry for the customer’s group with `"display": false` to the variant’s `sparklayer.settings` metafield. To hide it from every B2B customer, use the `base` group. Where: Products > select a variant > Metafields (Shopify admin). See [Product settings](https://docs.sparklayer.io/help/storefront/product-settings.md).
- **C. Install B2B Catalogs and enable it on your live theme** Without it, tags such as `b2b-only` and the visibility metafield can’t hide products on your theme’s pages. Install the free app, then enable it on your live (published) theme. See [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md).
- **D. Turn B2B Catalogs off and on again on your live theme** After app updates or theme changes, the live theme may not have the latest B2B Catalogs code. Turn it off and on again on the live theme. If the product still shows in a section, send us the page link. See [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md).
- **E. Everything checks out** Your setup looks right, so we'll take it from here. Send us your answers with the product link and the customer’s email.
- **F. Fix the JSON** Retype the quotes as straight quotes, correct the formatting and save. Copy an example from Product settings as a starting point. See [Product settings examples](https://docs.sparklayer.io/help/storefront/product-settings.md).
- **G. Tag the product** Add `b2b-only` to keep it from retail shoppers, or set up a catalog for the groups that should see it. Where: Products > select the product (Shopify admin). See [Catalogs per customer group](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-advanced-catalogs.md).

## FAQs

**Do I need to include every setting in the value?**

No. Include `customer_group` and the settings you want to set. Remove the others, or set them to `null`.

**Why aren't my settings being applied?**

Check that:

- The metafield is **enabled in SparkLayer**, at **Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app (**Metafields** card).
- The field is **on the variant**, not the product, and its definition reads exactly `sparklayer.settings`.
- Each `customer_group` is the group's **handle**, such as `trade`, not its Shopify tag, such as `b2b-trade`. To find it, click the group's name at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app.
- The value has a `base` entry. Groups without an entry of their own get the `base` settings.
- You've allowed about 10 minutes for the change to sync.
- The JSON uses **straight quotes**. If you typed the value by hand, rebuild it with the [form](#set-product-settings-for-a-customer-group) and paste it in again: a missing comma or a curly quote mark stops it working.
- You've put pack sizes and quantity limits **inside the JSON**. The individual metafields, such as `sparklayer.pack_size`, are ignored on a variant that has a `sparklayer.settings` value. See [Which rule wins](#which-rule-wins).


---

# Forms

URL: https://docs.sparklayer.io/help/forms

Build B2B forms such as trade account applications and credit requests in SparkLayer Forms, embed them on your store and act on entries with workflows.

> **Quick summary**
>
> - SparkLayer Forms is a no-code form builder. Use it to collect information from customers, such as trade account applications, credit requests and contact enquiries, without a third-party app.
> - Forms are in the **SparkLayer Dashboard** (app.sparklayer.io) only, at **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)). They aren't in the SparkLayer Wholesale app in Shopify admin. Shopify merchants sign in to the Dashboard to build forms and review entries.
> - For trade account applications, the quickest start is the **Wholesale Registration Form** [template](#start-from-a-template): when you approve an application, it creates the customer in your store with their customer group.
> - Forms are included on every plan. [Form workflows](https://docs.sparklayer.io/help/forms/workflows.md) (automations) are on the Growth plan and above: see [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md). They send submission emails and run the **Approve** and **Reject** buttons on entries, so without them you review entries and create customers yourself.

## What you can use Forms for

Use Forms wherever your B2B journey needs structured information from a customer or your team:

- Wholesale or B2B registration (trade account applications)
- Account credit or returns requests (see the [worked example](https://docs.sparklayer.io/help/forms/account-credit-request-form.md))
- Contact or enquiry forms, including internal ones for your team
- Capturing structured customer data, such as VAT IDs, trade references and licences
- Approval and onboarding processes, such as editing sales agent details

## How it works

Every form follows the same lifecycle. You build it, publish a version, add it to your store, then review the entries that arrive. Workflows can act on each entry automatically.

The lifecycle of a form:

1. **Build**: Add fields, pages, logic and validation in the form builder.
2. **Publish a version**: Your draft becomes the live version customers see.
3. **Embed on your store**: Add the form with the Shopify block or an embed code.
4. **Entries arrive**: Each submission is saved as an entry you can review and edit.
5. **Workflows act**: Send emails, create customers or call other systems.

**Everything Forms includes**

| Area | What you can do |
| --- | --- |
| **Form builder** | Build forms with a drag-and-drop builder. Add text, email, phone, dropdown, checkbox, date, address and file upload fields, set fields as required or optional, apply validation (such as email, phone or tax ID formats), show or hide fields with conditional logic, and split forms into pages with headers, dividers and progress indicators. Customers can save their progress and return later. |
| **Internal fields** | Add a separate set of fields that only your team sees when reviewing entries, such as a review status or approval buttons. Customers never see them. Internal fields support the same features as the main form, including display logic, validation, pages and workflows. |
| **Publishing** | Preview forms before publishing, embed them on your storefront, create internal-only forms for your team, and customise the success message shown after submission. |
| **Branding** | Style forms to match your site with CSS variables, and customise labels, help text and messages. |
| **Entries** | View all submissions in one place, approve or reject applications, review answers and uploaded files, update internal fields, track timestamps and status, and export entries to CSV. |
| **Workflows** | Automate what happens when an entry is submitted, a field changes, an admin clicks a button or an API call is made. Steps can assign approved customers to customer groups, apply tags, map form data to your platform (such as metafields or customer data), call your ERP or another system, and send emails. |

## Where to find Forms

Forms has two screens in the SparkLayer Dashboard. **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)) holds your forms and their entries. **Forms > Data tables** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms/tables)) holds your [data tables](https://docs.sparklayer.io/help/forms/data-tables.md).

**Shopify only:**

> **Using the Shopify app?**
>
> Forms and Data tables aren't in the SparkLayer Wholesale app in Shopify admin. Sign in to the SparkLayer Dashboard at app.sparklayer.io to use them. Forms you build there can still go on your Shopify store with the **SparkLayer Form** theme block: see [Embed and style a form](https://docs.sparklayer.io/help/forms/embedding-and-styling.md).

The **Forms** screen lists your forms, with their status and new entries:

| Column | What it shows |
| --- | --- |
| **Form** | The form's name, with when it was last updated. Click it to see its entries. |
| **Status** | **Published** (live on your store) or **Draft**. |
| **Entries** | How many entries it has. |
| **Unread** | How many entries are new, for example "2 new", or "None". |

Each row has **View entries**, and a **⋯** menu with **Edit form**, **Duplicate** and **Archive**.

## Start from a template

A template is the quickest way to start. The **Start from a template** card on the Forms screen has two. Click one to create a draft form, which you can customise with extra fields and workflows before you publish it.

| Template | What it includes |
| --- | --- |
| **Wholesale Registration Form** | Prospective buyers apply for a trade account, with an approve/reject workflow and email notifications. Approving an application creates the customer in your store with their customer group's tag, so they see trade prices when they sign in. |
| **Contact Us Form** | A simple contact form that notifies you of new submissions and sends an automatic reply. |

To start from scratch instead, click **Start with a blank form**. The form builder opens with an empty page. See [Build a form](https://docs.sparklayer.io/help/forms/setup.md).

## Guides

Follow these in order the first time you build a form.

- [Build a form](https://docs.sparklayer.io/help/forms/setup.md): Create a form, organise it into pages and groups, add internal fields and set its title and success message.
- [Field types](https://docs.sparklayer.io/help/forms/field-types.md): Every field you can add, from text and email to file upload, address and repeatable groups.
- [Conditional logic](https://docs.sparklayer.io/help/forms/conditional-logic.md): Show or hide fields, groups and pages based on answers or the logged-in customer.
- [Validation rules](https://docs.sparklayer.io/help/forms/validation.md): Check answers before a form can be submitted, with built-in and custom rules.
- [Versions and publishing](https://docs.sparklayer.io/help/forms/versions.md): Edit a draft safely, preview it and publish it as the live version.
- [Embed and style a form](https://docs.sparklayer.io/help/forms/embedding-and-styling.md): Add a form to your store, match it to your brand with CSS variables and translate it.
- [Form entries](https://docs.sparklayer.io/help/forms/entries.md): Review, filter, edit and export the submissions your forms receive.
- [Form workflows](https://docs.sparklayer.io/help/forms/workflows.md): Automate emails, approvals, customer creation and API calls.
- [Data references](https://docs.sparklayer.io/help/forms/data-references.md): Use answers, customer data, purchases and other SparkLayer data in logic, options and templates.
- [Data tables](https://docs.sparklayer.io/help/forms/data-tables.md): Keep reusable lists, such as sales territories or approved tax numbers, in one place.
- [Account credit request form](https://docs.sparklayer.io/help/forms/account-credit-request-form.md): A worked example: build a credit request form with internal review and approval workflows.


---

# Build a form

URL: https://docs.sparklayer.io/help/forms/setup

Create a SparkLayer form, organise it into pages, fields and groups, add internal fields for your team and set its title, success message and notifications.

> **Quick summary**
>
> - Create a form at **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)) with **Start with a blank form**, or from a template. Forms is only in the SparkLayer Dashboard, not in the SparkLayer Wholesale app in Shopify admin.
> - A form is made of pages, and each page holds fields. Groups bundle related fields together. Fields customers fill in go on the **Form** tab, and fields only your team sees go on the **Internal fields** tab.
> - The **Settings** tab controls the title, description, submit button text, language and success message customers see.
> - The templates come with a **Notification of submission** workflow that emails your team about each new entry. You can edit it on the **Workflows** tab. Workflows are on the Growth plan and above: see [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).

## How it works

You build a form in the form builder, without code. Every form has the same structure:

| Level | What it is |
| --- | --- |
| **Form** | The main container. |
| **Pages** | Sections of the form. A short form can have one page; longer forms can have several steps. |
| **Fields** | The individual inputs customers fill in. See [Field types](https://docs.sparklayer.io/help/forms/field-types.md). |
| **Groups** | Related fields, nested together inside a group. |

The form builder has six tabs:

| Tab | What it's for |
| --- | --- |
| **Form** | The fields customers fill in, page by page. |
| **Preview** | How the form looks to buyers right now. |
| **Internal fields** | Fields only your team sees on each entry, such as the decision on an application. |
| **Workflows** | Your [automations](https://docs.sparklayer.io/help/forms/workflows.md): what happens when an entry comes in or a decision is made. |
| **Settings** | What buyers see (title, description, button text, language, success message) and settings for your team. |
| **Embed** | How to [add the form to your store](https://docs.sparklayer.io/help/forms/embedding-and-styling.md) or another website. |

The form's name and status (**Draft** or **Published**) show at the top. **Publish** appears while the form has unpublished changes. **More actions** has **View entries**, **Duplicate** and **Archive**.

## Create a form

1. In the SparkLayer Dashboard, go to **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)).
2. On the **Start from a template** card, click **Start with a blank form**. The form builder opens with an empty page.
3. On the **Settings** tab, enter a **Form title**, for example "Trade account request". Customers see this title when they view the form.
4. Optionally, enter an **Internal title**, such as "Trade account request (UK)". It's only shown in the Dashboard.
5. Click **Save** in the save bar.

Then [add fields](#add-fields) on the **Form** tab.

To start from a ready-made form instead, click **Wholesale Registration Form** or **Contact Us Form** on the same card. Each creates a draft you can edit before publishing. See [Start from a template](https://docs.sparklayer.io/help/forms.md#start-from-a-template).

## Add pages

Pages divide a form into sections. A single page suits short forms, where customers see everything at once. Use several pages when you have lots of fields, or want to break the form into steps with clearer progress.

1. On the **Form** tab, click **+ Add page above**. 
2. Give the page a **Title**, shown to customers as a heading. 
3. [Add fields](#add-fields) to the page. The order of pages sets the order customers move through the form. 

## Add fields

1. On the **Form** tab, click **Add field**, then choose a [field type](https://docs.sparklayer.io/help/forms/field-types.md).
2. Click **Edit** on the field to open its settings. They have three tabs: **Properties**, **Validation** and **Display logic**.
3. On **Properties**, enter a **Label** and any other settings you need (see the table below).
4. Drag the handle on a field to reorder it, or click the bin icon to delete it.

Changes save automatically to your draft. Customers only see them once you [publish](https://docs.sparklayer.io/help/forms/versions.md).

Each field on the **Form** tab shows its label (with \* when it's required) and its type, such as **Email** or **Select**. These are the settings on the **Properties** tab:

| Property | What it does |
| --- | --- |
| **Label** | The field name shown to customers. Required. |
| **Description** | Optional help text shown with the field. |
| **Required** | Customers must fill in the field before they can submit. |
| **Read only** | Shows the field but prevents editing. |
| **Repeatable** | Customers can add the field more than once. |
| **Placeholder** | Hint text inside the field. |
| **Default value** | Pre-filled content. Can use [data references](https://docs.sparklayer.io/help/forms/data-references.md), for example the logged-in customer's email. |

Rules on the **Validation** tab are covered in [Validation rules](https://docs.sparklayer.io/help/forms/validation.md), and the **Display logic** tab in [Conditional logic](https://docs.sparklayer.io/help/forms/conditional-logic.md).

## Group related fields

A **Group** field holds other fields, for example a "Contact information" group with first name, last name and email. Groups:

- Keep layouts clean and the form easier to read
- Structure complex data
- Let you apply display logic to several fields at once

### Repeatable groups

To let customers add the same set of fields more than once, turn on **Repeatable** for the group. This suits order lines, locations or team members. Customers can add, remove and reorder each set.

A field can be top-level (placed directly on a page), nested inside a group, or repeatable.

## Add internal fields

Internal fields are a second set of fields that only your team sees when reviewing an entry, for example a decision, reviewer notes or a button that runs a workflow. Customers never see them.

The **Wholesale Registration Form** template comes with these internal fields:

| Field | Type | What it's for |
| --- | --- | --- |
| **Decision** | Toggle | Approve or reject the application. |
| **Customer group** | Select | Shown when approved: the group, and so the prices, the buyer gets. |
| **Tax exempt** | Checkbox | Shown when approved. |
| **Apply decision** | Workflow trigger button | Runs the **Approve/Reject workflow**. |
| **Application status** | Select | Pending, Approved or Rejected. |
| **Error message** | Long text | Shown when a workflow fails. |

1. Open the form and go to the **Internal fields** tab.
2. Add fields in the same way as on the **Form** tab. Internal fields support everything the main form does, including pages, display logic, validation and workflows.
3. To run a workflow from a button, add a **Workflow trigger button** field and use the **Internal button clicked** trigger in [Form workflows](https://docs.sparklayer.io/help/forms/workflows.md).

You fill in internal fields when you open an [entry](https://docs.sparklayer.io/help/forms/entries.md). Changes to them can also run workflows, with the **Internal field updated** trigger.

## Preview your form

1. Click the **Preview** tab.
2. Fill in the form to test fields, validation and logic.
3. Go back to the **Form** tab to make any changes.

Preview entries are kept separate from real ones. The preview has no logged-in customer, so test forms that rely on customer data on your store. See [Versions and publishing](https://docs.sparklayer.io/help/forms/versions.md#preview-a-draft).

## Configure form settings

Open the **Settings** tab to set what customers see and how your team manages entries, then click **Save** in the save bar.

| Card | Setting | What it does |
| --- | --- | --- |
| **What buyers see** | **Form title** | The title shown to customers filling in the form. |
| **What buyers see** | **Description** | A line of instructions under the title. |
| **What buyers see** | **Submit button text** | The wording on the submit button. |
| **What buyers see** | **Language** | Translates built-in text, like buttons and address lookup: Default (English), Dutch, French, German, Italian or Spanish. Your own labels aren't translated: see [Translate a form](https://docs.sparklayer.io/help/forms/embedding-and-styling.md#translate-a-form). |
| **What buyers see** | **Success message** | The message shown after a customer submits. It can include the customer's answers and other details with [data references](https://docs.sparklayer.io/help/forms/data-references.md), such as `{{name}}`. It can also use conditions, loops and HTML. |
| **For your team** | **Internal title** | A name only shown in the Dashboard, for example "Trade applications". Useful when it should differ from the public title. |
| **For your team** | **Read/unread tracking** | Marks entries as read or unread, and counts new ones on the Forms screen. |

## Get notified of new submissions

The **Wholesale Registration Form** and **Contact Us Form** templates come with a **Notification of submission** workflow, which emails your team whenever an entry is submitted.

To change the recipient or add more logic, open the **Workflows** tab and click **View** next to that workflow. For a blank form, add a workflow with the **Form submitted** trigger and a **Send email** step. See [Form workflows](https://docs.sparklayer.io/help/forms/workflows.md).

> **Notification emails need workflows**
>
> Submission emails are sent by a workflow, and workflows are on the Growth plan and above (see [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md)). On a plan without them, no email is sent: check the form's [entries](https://docs.sparklayer.io/help/forms/entries.md) yourself for new submissions. Shopify Flow can't start from a SparkLayer form submission, so it can't send the email for you either.

## Field IDs and how answers are stored

Every field has an internal ID, used by conditional logic, workflows and data references. Keep IDs short, simple and consistent, so template references stay short.

**How answers are stored**

Answers are stored following the structure you build:

| Structure | Example |
| --- | --- |
| **Simple field** | `email` |
| **Nested field** | `contact.first_name` |
| **Repeatable group** | `items[instance1].quantity`, `items[instance1].sku`, `items[instance2].quantity`, `items[instance2].sku` |

You rarely need to work with these paths directly, but they help when building workflows or automations.

## Tips

- Group related fields together.
- Split very long pages into several pages.
- Avoid several levels of nested groups.
- Use consistent naming for labels and field IDs.

## Next steps

- [Versions and publishing](https://docs.sparklayer.io/help/forms/versions.md): Preview your draft and publish it as the live version.
- [Embed and style a form](https://docs.sparklayer.io/help/forms/embedding-and-styling.md): Add the form to your store.
- [Form workflows](https://docs.sparklayer.io/help/forms/workflows.md): Send emails and approve customers automatically.


---

# Field types

URL: https://docs.sparklayer.io/help/forms/field-types

Choose the right field for each question in SparkLayer Forms, from text, email and date inputs to selects, file uploads, signatures, addresses and groups.

> **Quick summary**
>
> - Each field type collects one kind of input, such as text, a date, a choice from a list or a file. Pick the type that matches the question.
> - Add fields with **Add field** on the **Form** or **Internal fields** tab of the form builder, at **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)). Forms is only in the SparkLayer Dashboard, not in the SparkLayer Wholesale app in Shopify admin.
> - Choice fields can take their options from a list you type, or from a [data source](https://docs.sparklayer.io/help/forms/data-references.md) such as a data table or the customer's purchases.
> - You can open files customers upload from their [entry](https://docs.sparklayer.io/help/forms/entries.md).

## How it works

A field's type sets how it looks, what customers can enter and the built-in [validation](https://docs.sparklayer.io/help/forms/validation.md) it gets. To add a field, see [Build a form](https://docs.sparklayer.io/help/forms/setup.md#add-fields).

## Standard input fields

Use these for basic customer information. They support validation such as required values, length limits and number ranges.

| Field | Best for |
| --- | --- |
| **Text** | Names, company details, references. |
| **Email** | Contact email addresses. |
| **Long text** | Longer notes or requests. |
| **Number** | Quantities, values or other numbers. |
| **Phone** | Phone numbers with country codes. |
| **Password** | Secure login or gated forms. |
| **URL** | Website addresses or other links. |

## Date and time fields

Use these for dates and times, such as delivery dates. When you configure the field, you can set the allowed range and availability.

| Field | Best for |
| --- | --- |
| **Date** | Delivery dates, deadlines. |
| **Time** | Appointment times. |
| **Date & Time** | Combined date and time. |

## Selection fields

Use these when customers choose from set options. Type the options yourself, or pull them from a data source with [data references](https://docs.sparklayer.io/help/forms/data-references.md#use-references-as-options).

| Field | What it does |
| --- | --- |
| **Select** | A dropdown with one choice. |
| **Multiple choice** | Choose several options from a list. |
| **Radio** | One choice, with the options shown inline. |
| **Toggle** | An on/off switch, for example to confirm something. |
| **Checkbox** | An on/off choice shown as a checkbox. |
| **Slider** | A numeric range. |
| **Country** | One country. |

## Advanced input fields

Use these for richer information.

| Field | Best for |
| --- | --- |
| **Rating** | Feedback or scoring. |
| **Signature** | Agreements or approvals. |
| **File Upload** | Documents, images and other attachments, such as a resale certificate. You can open them from the [entry](https://docs.sparklayer.io/help/forms/entries.md). |
| **Hidden** | Values customers don't see, such as tracking or integration data used by automations. |
| **Tax Information** | Tax details such as a VAT number or tax ID. |
| **Workflow trigger button** | A button that runs a [workflow](https://docs.sparklayer.io/help/forms/workflows.md). Mostly used on internal fields rather than the customer-facing form. |

**For developers: uploaded files**

A **File Upload** answer is stored as a SparkLayer file ID. Use the [Files API](https://docs.sparklayer.io/developers/api/files/get-bulk-files.md) to turn it into a download link.

## Structured fields

These fields create several sub-fields for you. That keeps answers consistent, especially for B2B account requests and onboarding.

| Field | What it includes |
| --- | --- |
| **Name** | Title, first name, last name. |
| **Address** | Street, city, postcode, country. |

## Layout and grouping fields

Use these to organise the form.

| Field | What it does |
| --- | --- |
| **Group** | Keeps related fields together and lets you apply [display logic](https://docs.sparklayer.io/help/forms/conditional-logic.md) to all of them at once. |
| **Group** with **Repeatable** on | Lets customers add the same set of fields more than once, for example one row per line item. |

See [Group related fields](https://docs.sparklayer.io/help/forms/setup.md#group-related-fields) for how groups work.

## Content fields

These fields don't collect answers. Use them to guide customers through the form.

| Field | Best for |
| --- | --- |
| **Heading** | Section titles. |
| **Paragraph** | Instructions or context. |
| **Image** | Visual guidance. |
| **Video** | Embedded videos. |
| **Button** | A link or a workflow trigger. |
| **HTML** | Custom content blocks. |

## Tips

- Use structured fields (**Name**, **Address**) for consistent answers.
- Use **Select** or **Radio** when there's a fixed set of answers.
- Break long forms into [pages](https://docs.sparklayer.io/help/forms/setup.md#add-pages) and groups.
- Only ask for information you need.


---

# Conditional logic

URL: https://docs.sparklayer.io/help/forms/conditional-logic

Show or hide fields, groups and pages in SparkLayer Forms based on answers or the logged-in customer, using AND/OR conditions and condition groups.

> **Quick summary**
>
> - Conditional logic (display logic) shows or hides a field, group or page based on other answers, so customers only see questions that apply to them.
> - You set it per field on the **Display logic** tab of **Configure field** in the form builder, at **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)). Forms is only in the SparkLayer Dashboard, not in the SparkLayer Wholesale app in Shopify admin.
> - A condition compares an answer against a value you type. It can also compare against [data references](https://docs.sparklayer.io/help/forms/data-references.md), such as the logged-in customer's customer group.
> - Hidden fields aren't validated, and their **Required** setting is ignored.

## How it works

Each field can have rules that decide when it appears. When a customer changes an answer, SparkLayer checks your conditions and shows or hides fields straight away. You set it all up in the form builder, without code.

A condition has three parts:

| Part | What it is |
| --- | --- |
| **Field** | The answer or value you're checking. |
| **Condition** | How it's compared, such as **Equals**. |
| **Value** | What it's compared against: a fixed value, or a reference. |

For example: show **State** when **Country** equals "US".

You choose whether the conditions show the field or hide it:

| Action | What it does | Use it for |
| --- | --- | --- |
| **Show when** | The field only appears when the conditions are met. | Region-specific address fields, optional business details or advanced settings. |
| **Hide when** | The field disappears when the conditions are met. | Skipping irrelevant questions and shortening long forms. |

## Common uses

Use conditional logic to keep forms short and relevant:

| Use | How |
| --- | --- |
| **Region-based forms** | Show different fields depending on the country selected. |
| **Advanced options** | Hide detailed options until a toggle is turned on. |
| **Progressive disclosure** | Reveal extra questions gradually instead of showing a long form up front. |
| **Customer-dependent forms** | Show or hide sections based on the logged-in customer's ID, customer group, role or other details. |

## Add conditional logic to a field

1. In the form builder, select the field (or group) you want to show or hide.
2. In **Configure field**, open the **Display logic** tab.
3. Under **Conditional display logic**, click **Add condition** and choose the **Field** to check. For a field from elsewhere, or for customer or SparkLayer data, use the reference picker. 
4. Choose a **Condition**, such as **Equals**.
5. Enter a **Value**, or click **Reference** to compare against another answer or data reference.
6. To combine several rules with AND or OR, turn on **Advanced rules**. 

Changes save to your draft automatically. To remove all rules from the field, click **Clear logic**.

To apply the same logic to several fields at once, put them in a **Group** and add the logic to the group.

## Combine conditions

One condition is often enough. For more complex rules, combine conditions with AND or OR, or group them.

| Type | Example |
| --- | --- |
| **Single condition** | Show **Phone** when **Contact preference** equals "Call". |
| **Multiple conditions** (AND or OR) | Show **Shipping address** when **Delivery method** equals "Ship" AND **Country** equals "United Kingdom". |
| **Condition groups** | Show **Discount** when (**Customer type** equals "Premium" OR **Order total** is greater than 1000) AND **Promotions enabled** is true. |

With condition groups, you can build complex rules without duplicating fields.

## Condition types

The conditions you can choose depend on the type of field:

| Type | Examples |
| --- | --- |
| **Equals / not equals** | Customer type equals "Trade". |
| **Greater than / less than** | Order value is greater than 500; quantity is at least 10. |
| **Contains** | Email contains "@company". |
| **Starts with** | Phone starts with "+44". |
| **Ends with** | Email ends with ".edu". |
| **Has value** | Email is not empty. |
| **True / false** | Approved is true. |
| **Length** | Checks on the length of a postcode, reference code or order number. |

## What you can reference

Conditions can compare against a value you type, or against other data with [data references](https://docs.sparklayer.io/help/forms/data-references.md), such as the logged-in customer's customer group.

**What references can point to**

- Fields on the same page or earlier pages
- Global (non-repeating) fields
- Fields in the same instance of a repeatable group (inside a repeatable group, logic applies to the current item)
- Fields from other forms
- Data table values
- The logged-in SparkLayer customer, such as their ID, customer group, role and other details

## Hidden field behaviour

Hiding a field changes how the form treats it. When a field is hidden:

- It's removed from the form
- Its validation rules no longer apply
- Its **Required** setting is ignored
- Its value is kept, unless configured otherwise

To clear an answer when the field it depends on changes, use a [Clear answer workflow](https://docs.sparklayer.io/help/forms/workflows.md#reset-a-dependent-field).

## Tips

- Keep logic simple. Avoid deeply nested conditions, use clear labels and write down complex rules for your team.
- Use a **Group** to apply logic once to several fields instead of repeating it.
- Test every condition path, including empty fields, on the **Preview** tab.
- Don't hide too much at the start, and give context when new fields appear.
- Very complex logic can slow down large forms. If a form grows, split it into pages, simplify nested conditions and reduce dependencies between fields.


---

# Validation rules

URL: https://docs.sparklayer.io/help/forms/validation

Check answers in SparkLayer Forms before they're submitted, with built-in format checks and custom rules using text, number, length and cross-field conditions.

> **Quick summary**
>
> - Every field gets built-in checks for its type, such as a valid email address. To add your own business rules, add custom validation rules, each with an error message.
> - You add rules per field on the **Validation** tab of **Configure field** in the form builder, at **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)). Forms is only in the SparkLayer Dashboard, not in the SparkLayer Wholesale app in Shopify admin.
> - A rule's condition describes the answers you **allow**: the error shows when the condition is false.
> - Validation runs while the form is filled in and whenever an entry is edited. A form can't be submitted while any rule fails.

## How it works

Validation stops incorrect data reaching your team, workflows and store. It works in layers, and the first two need no code:

Layers of validation:

1. **Built-in checks**: Format checks for each field type, with no setup.
2. **Custom rules**: Your business rules, such as a minimum length or matching values.
3. **Workflows**: Advanced checks, such as against an external system.

### Built-in checks

Each field type checks its own format, with no setup:

| Field type | Built-in check |
| --- | --- |
| **Email** | A valid email structure. |
| **URL** | A valid web address. |
| **Number** | A number within range. |
| **Date** | A valid date. |
| **Phone** | Valid digits. |
| **File upload** | File type and size limits. |

To make a field mandatory, tick **Required** on the field's **Properties** tab.

## Add a validation rule

Add a custom rule when the built-in checks aren't enough, for example to require a minimum length.

1. In the form builder, select the field.
2. In **Configure field**, open the **Validation** tab.
3. Click **Add rule**.
4. Set the **Condition**: the values you want to allow.
5. Enter the **Error message** customers see when the condition isn't met.

Changes save to your draft automatically.

> **Describe what's allowed, not what's blocked**
>
> A rule's error message shows when its condition is false, not when it matches. Say you don't ship to the United Kingdom. Don't set the condition to "country equals United Kingdom": that shows the error for every other country. Instead, set it to the countries you do ship to, such as "country is one of France, Germany, Spain". The error then only shows for a country outside that list.

## Types of rule

A rule can check a field on its own, or against other data:

| Type | What it checks | Examples |
| --- | --- | --- |
| **Simple value rules** | A field's own answer. | "Must be at least 10 characters", for password strength, reference numbers and minimum input. |
| **Cross-field and data reference rules** | An answer against another field, or against other data through [data references](https://docs.sparklayer.io/help/forms/data-references.md). | The confirmation email matches the email; the end date is after the start date; a purchase ID matches one of the customer's SparkLayer purchases. |

## Operators

Validation uses the same operators as [conditional logic](https://docs.sparklayer.io/help/forms/conditional-logic.md). Which ones you can choose depends on the type of field.

**Every operator**

| Operator | Example use |
| --- | --- |
| **Matches pattern** | A regular expression (regex) format check. |
| **Contains** | Must include a value. |
| **Starts with** | A required prefix. |
| **Ends with** | A required suffix. |
| **Greater than / equal** | A minimum quantity. |
| **Less than / equal** | A maximum value. |
| **Equals / not equals** | An exact match. |
| **Minimum length** | Password rules. |
| **Maximum length** | Reference codes. |
| **Exact length** | Postcodes or IDs. |
| **Is email** | An email format check. |
| **Is number** | A numeric value. |
| **Is integer** | A whole number. |
| **Is alpha / alphanumeric** | Letters only, or letters and numbers. |

Common patterns include making sure an end date is after a start date, and preventing duplicate items in a repeatable group or multi-select field.

## Write error messages

A good error message says what's wrong and how to fix it, in plain words. For example, write "Phone number must include area code", not "Invalid input". Messages can include values through templates, such as the required minimum.

## Validation states

A form can only be submitted when every rule passes.

**The three validation states**

| State | What it means |
| --- | --- |
| **Valid** | All rules pass. The form can be submitted. |
| **Invalid** | One or more rules fail. The form can't be submitted. |
| **Pending** | A check is still running. The form can't be submitted yet. |

Before a customer interacts with a field, it shows no indicator. After that, it shows an error message when invalid, and optionally a success indicator.

## Validate with workflows

For checks the form can't do itself, use [workflows](https://docs.sparklayer.io/help/forms/workflows.md). A workflow can run on submission, a page change or an answer update. It can run advanced checks, validate against external systems and apply logic across forms. Inside a workflow, **Condition** steps can update answers, notify your team about invalid data or start follow-up actions.

## Tips

- Layer your validation: built-in checks for format, custom rules for business logic, and workflows for advanced checks.
- Validate early rather than only on submit, show clear instructions, and avoid overly strict rules.
- Test empty values, the minimum and maximum, special characters and very long answers.
- Keep forms fast: avoid heavy regular expressions and complex cross-field rules where you can, and use workflows for advanced processing.


---

# Versions and publishing

URL: https://docs.sparklayer.io/help/forms/versions

Edit a SparkLayer form as a draft, preview it, publish it as the live version and understand how new versions affect existing and in-progress entries.

> **Quick summary**
>
> - You edit a form as a draft. Customers keep seeing the published version until you click **Publish**.
> - The form builder shows the form's status, **Draft** or **Published**, next to its name. Open it from **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)). Forms is only in the SparkLayer Dashboard, not in the SparkLayer Wholesale app in Shopify admin.
> - Publishing can include the form fields, the internal fields and the workflows. Existing entries keep the version they were created with, so publishing never changes them.

## How it works

Each form has versions, so you can change it without interrupting live submissions. A form is always in one of these states:

| State | What it means |
| --- | --- |
| **Draft** | Changes you're still working on. Customers don't see them. |
| **Published** | The live version, used for new submissions and for forms embedded on your store. Read only. |
| **Archived** | Older versions, kept for reference and for the entries created with them. |

A form has at most one draft and one published version at a time.

How a change goes live:

1. **Edit**: A draft is created from the published version. Changes save automatically.
2. **Preview**: Test the draft. Preview entries are kept separate.
3. **Publish**: The draft becomes the published version.
4. **Archive**: The previous published version is archived.

The top of the form builder shows the form's name and status. **Publish** appears while there are unpublished changes. The **More actions** menu has **View entries**, **Duplicate** and **Archive**. 

## Edit a draft

1. Open the form from **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)).
2. Make sure you're editing the draft.
3. Make your changes. They save automatically, and the live form stays the same.

When you start editing, SparkLayer creates the draft from the current published version. To look at what's live without changing anything, select **Published**.

## Preview a draft

1. Click the **Preview** tab.
2. Fill in the form to test your changes, including validation and conditional logic.

Preview entries are marked separately from real entries. Preview whenever you change the structure, logic or workflows.

The preview has no logged-in customer. If your form uses customer or purchase data, test it on your store instead. Use a page where the SparkLayer Core Script is loaded, signed in as a customer. The page can be hidden while you test.

## Publish changes

1. Click **Publish**.
2. Choose what to publish (see the table below).
3. Add a summary of your changes. It's kept for future reference, which helps with audits.
4. Confirm. The draft becomes the published version. 

| Option | What it publishes |
| --- | --- |
| **Form fields** | The main form customers see. |
| **Internal fields** | The admin fields shown against entries. |
| **Workflows** | Your automations and their logic. |

The previous published version is archived, and all new submissions use the new version.

## How versions affect entries

Publishing never changes entries you already have. Which version an entry uses depends on when it was started:

| Entry | Which version it uses |
| --- | --- |
| **New submissions** | Always the current published version, with its fields, validation and workflows. |
| **Existing entries** | The version they were created with. Their data structure and workflows stay the same. |
| **In-progress entries** | If a customer started the form before you published, they continue on the version they began with. They see your changes the next time they start a new submission. |

## Tips

- Publish all affected areas (form fields, internal fields and workflows) together where you can.
- Always write a clear summary in the **Publish** dialog.
- Test a new version before you share the form.
- To completely rethink a form, create a new form rather than reworking the existing one.

## Next steps

- [Build a form](https://docs.sparklayer.io/help/forms/setup.md): Create a form and organise it into pages, fields and groups
- [Form workflows](https://docs.sparklayer.io/help/forms/workflows.md): Automate what happens after a customer submits a form
- [Form entries](https://docs.sparklayer.io/help/forms/entries.md): Review, approve and export the submissions your form collects


---

# Embed and style a form

URL: https://docs.sparklayer.io/help/forms/embedding-and-styling

Add a SparkLayer form to your store with the Shopify theme block or an embed code, set embed attributes and match it to your brand with CSS variables.

> **Quick summary**
>
> - On Shopify, add a published form with the **SparkLayer Form** block in the theme editor, with no code. On any other platform or website, paste the embed code from the form's **Embed** tab, at **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)).
> - You build forms in the SparkLayer Dashboard (Forms isn't in the SparkLayer Wholesale app in Shopify admin), but they work on your Shopify store.
> - Forms use your SparkLayer theme styles automatically. To make forms look different from the rest of SparkLayer, your developer can set `--spark-form-*` CSS variables.
> - Only the published version appears on your store, so [publish](https://docs.sparklayer.io/help/forms/versions.md#publish-changes) your form first.
> - To show a form in several languages, make one copy per language. See [Translate a form](#translate-a-form).

## Add a form to your store

**Shopify:**

Most Shopify stores should use the **SparkLayer Form** block. In the theme editor, you pick a form and set common layout and styling options, without adding code.

1. In the SparkLayer Dashboard, open the form from **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)). Go to the **Embed** tab and click **Open theme editor**. Or, in your Shopify admin, go to **Online Store > Themes** ([open in the Shopify admin](https://admin.shopify.com/themes)) and click **Customize**.
2. Open the page where you want the form, and add the **SparkLayer Form** block to a section.
3. Select the form you want to show.
4. Adjust the styling options in the block's settings.
5. Click **Save**. The form is now on your store.

When you publish changes to the form later, they show on your store straight away. To share the form as a link instead, click **Copy registration link** on the **Embed** tab.

If your form isn't in the block's dropdown, open the **SparkLayer Wholesale** app under Sales channels in your Shopify admin and accept any new permissions it asks for.

For more control, use the embed code instead: see the **Other platforms** tab.

**Other platforms:**

1. In the SparkLayer Dashboard, go to **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)) and open your form.
2. Click the **Embed** tab and, under **Another website**, click **Copy code**. The code always shows the latest published version.
3. Paste the code into your theme or page content where you want the form to appear.
4. Save your changes and check the form on your store.

## Translate a form

A form's **Language** setting (on the **Settings** tab) only translates built-in text, such as buttons and the address lookup. The labels, descriptions and messages you write stay as you wrote them. Forms aren't covered by the [Core Script translations](https://docs.sparklayer.io/help/storefront/languages-and-international.md) either. On Shopify, Translate & Adapt can't translate a form's field labels, because the form loads as an embed.

To show a form in several languages, make one form per language:

1. At **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)), open the form's **⋯** menu and click **Duplicate**. Make one copy for each language.
2. In each copy, rewrite the labels, descriptions, button text and success message in that language, and set its **Language** if it's listed. See [Configure form settings](https://docs.sparklayer.io/help/forms/setup.md#configure-form-settings).
3. [Publish](https://docs.sparklayer.io/help/forms/versions.md#publish-changes) each copy.
4. Copy each form's embed code from its **Embed** tab (under **Another website**, **Copy code**).

Then show each language's form on your store:

**Shopify:**

These steps are for the [B2B login page](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md#embed-a-sparklayer-form), with your default language's embed code in its **Custom Contact Form HTML** setting.

1. Open Shopify's [Translate & Adapt app](https://apps.shopify.com/translate-and-adapt) and choose a language at the top.
2. Under **Theme**, click **Templates**, then select **Page: B2B Login**.
3. Find the field **Main: Custom Form Html** and paste that language's embed code.
4. Save, then repeat for each language.

Your theme needs a language selector, so customers can switch language and see the right form.

**Other platforms:**

Add each language's embed code to the version of the page for that language.

Entries arrive on each copy separately, so check the entries of every language's form.

## Style a form

Forms match the rest of SparkLayer on your store automatically, so most stores don't need to change anything.

**Shopify only:**

On Shopify, the **SparkLayer Form** block also has styling options you can set in the theme editor, without code.

To make forms look different from the rest of SparkLayer, your developer or agency can set CSS variables.

**Code for your developer**

Embedded forms use the same core CSS variables as the rest of SparkLayer. If the SparkLayer Core Script already sets `--spark-*` variables on your storefront, forms pick them up automatically. See [Customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md) for your global styles.

To style forms differently from the rest of SparkLayer, set `--spark-form-*` variables on the `spark-form` element. Styles are applied in this order of priority:

1. `--spark-form-*` form-specific variables
2. `--spark-*` global SparkLayer variables
3. SparkLayer's default styles

For example:

```css
spark-form {
  --spark-form-max-width: 680px;
  --spark-form-button-color: #000000;
  --spark-form-button-raised-background: #000000;
  --spark-form-button-raised-color: #ffffff;
  --spark-form-link-color: #000000;
  --spark-form-border-radius-default: 4px;
}
```

See [Form CSS variables](#css-variables) for every variable.

## Embed a form manually (for developers)

This section is for your developer or agency, when they add the form by hand or need its options. The embed code has two parts. First, the SparkLayer form script:

```html
<script src="https://cdn.sparklayer.io/spark-form.v1.js"></script>
```

Then the form itself, placed where you want it to appear:

```html
<spark-form
form-id="your-form-id"
site-id="your-site-id">
</spark-form>
```

Your [site ID](https://docs.sparklayer.io/help/glossary.md#site-id) is in [Account settings](https://docs.sparklayer.io/help/dashboard/account.md).

### Embed attributes

| Attribute | Required | What it does |
| --- | --- | --- |
| `form-id` | Yes | The ID of the form to show. |
| `site-id` | Yes | Your SparkLayer site ID. |
| `site-env` | No | Set to `test` to load the form from your test environment. Defaults to live. |
| `entry-id` | No | Resumes an existing entry. |
| `entry-key` | No | The key needed to open an existing entry. |
| `hide-title` | No | Set to `true` to hide the form title. |
| `preview-version-id` | No | Previews a specific form version. |

## Form CSS variables (for developers)

Each form variable falls back to the matching global variable when it isn't set.

**All form CSS variables**

| Form variable | Falls back to | Controls |
| --- | --- | --- |
| `--spark-form-max-width` | None | Maximum form width |
| `--spark-form-button-width` | None | Button width, for example 100% |
| `--spark-form-font-default` | `--spark-font-default` | Main font family |
| `--spark-form-header-font` | `--spark-header-font` | Heading font family |
| `--spark-form-button-font-family` | `--spark-button-font-family` | Button font family |
| `--spark-form-font-default-size-small` | `--spark-font-default-size-small` | Base font size on smaller screens |
| `--spark-form-font-default-size` | `--spark-font-default-size` | Base font size |
| `--spark-form-input-font-size` | `--spark-input-font-size` | Input font size |
| `--spark-form-h1-fontsize` | `--spark-h1-fontsize` | H1 size |
| `--spark-form-h2-fontsize` | `--spark-h2-fontsize` | H2 size |
| `--spark-form-h3-fontsize` | `--spark-h3-fontsize` | H3 size |
| `--spark-form-h4-fontsize` | `--spark-h4-fontsize` | H4 size |
| `--spark-form-h5-fontsize` | `--spark-h5-fontsize` | H5 size |
| `--spark-form-h6-fontsize` | `--spark-h6-fontsize` | H6 size |
| `--spark-form-button-small-font-size` | `--spark-button-small-font-size` | Small button font size |
| `--spark-form-button-font-size` | `--spark-button-font-size` | Default button font size |
| `--spark-form-button-large-font-size` | `--spark-button-large-font-size` | Large button font size |
| `--spark-form-font-weight-default` | `--spark-font-weight-default` | Default font weight |
| `--spark-form-font-weight-medium` | `--spark-font-weight-medium` | Medium font weight |
| `--spark-form-font-weight-heavy` | `--spark-font-weight-heavy` | Heavy font weight |
| `--spark-form-header-font-weight` | `--spark-header-font-weight` | Heading font weight |
| `--spark-form-button-font-weight` | `--spark-button-font-weight` | Button font weight |
| `--spark-form-header-text-transform` | `--spark-header-text-transform` | Heading text transform |
| `--spark-form-header-letter-spacing` | `--spark-header-letter-spacing` | Heading letter spacing |
| `--spark-form-button-text-transform` | `--spark-button-text-transform` | Button text transform |
| `--spark-form-button-text-letter-spacing` | `--spark-button-text-letter-spacing` | Button letter spacing |
| `--spark-form-border-radius-default` | `--spark-border-radius-default` | Default border radius |
| `--spark-form-border-radius-button` | `--spark-border-radius-button` | Button border radius |
| `--spark-form-input-padding` | `--spark-input-padding` | Input padding |
| `--spark-form-button-padding` | `--spark-button-padding` | Button padding |
| `--spark-form-product-card-button-padding` | `--spark-product-card-button-padding` | Product card button padding |
| `--spark-form-lightest-color` | `--spark-lightest-color` | Form background and light surfaces |
| `--spark-form-default-body-color` | `--spark-default-body-color` | Body text colour |
| `--spark-form-header-color` | `--spark-header-color` | Heading colour |
| `--spark-form-primary-color` | `--spark-primary-color` | Primary colour |
| `--spark-form-primary-color-light` | `--spark-primary-color-light` | Light primary colour |
| `--spark-form-primary-color-dark` | `--spark-primary-color-dark` | Dark primary colour |
| `--spark-form-secondary-color` | `--spark-secondary-color` | Secondary colour |
| `--spark-form-link-color` | `--spark-link-color` | Link colour |
| `--spark-form-button-color` | `--spark-button-color` | Button brand colour |
| `--spark-form-button-raised-color` | `--spark-button-raised-color` | Primary button text colour |
| `--spark-form-button-raised-background` | `--spark-button-raised-background` | Primary button background |
| `--spark-form-button-raised-hover-background` | `--spark-button-raised-hover-background` | Primary button hover background |
| `--spark-form-button-raised-border-color` | `--spark-button-raised-border-color` | Primary button border colour |
| `--spark-form-button-disabled-color` | `--spark-button-disabled-color` | Disabled button text colour |
| `--spark-form-button-large-color` | `--spark-button-large-color` | Large button colour |
| `--spark-form-input-background` | `--spark-input-background` | Input background |
| `--spark-form-input-border-color` | `--spark-input-border-color` | Input border colour |
| `--spark-form-input-text-color` | `--spark-input-text-color` | Input text colour |
| `--spark-form-input-focus-border-color` | `--spark-input-focus-border-color` | Focused input border colour |
| `--spark-form-table-header-background-color` | `--spark-table-header-background-color` | Table header background |
| `--spark-form-success-color` | `--spark-success-color` | Success state colour |
| `--spark-form-error-color` | `--spark-error-color` | Error state colour |
| `--spark-form-warn-color` | `--spark-warn-color` | Warning state colour |
| `--spark-form-info-color` | `--spark-info-color` | Info state colour |
| `--spark-form-agent-color` | `--spark-agent-color` | Agent state colour |
| `--spark-form-company-users-color` | `--spark-company-users-color` | Company users state colour |

## FAQs

**The address search box clears after the customer picks an address**

That's expected. When the customer picks an address from the search, the address finder fills in the separate address fields (such as street, city and postcode) and clears the search box. The address is in the fields below it.

**Can Translate & Adapt translate my form?**

No. Translate & Adapt can't reach a form's field labels, because the form loads as an embed. Make one form per language and paste each one's embed code into Translate & Adapt instead. See [Translate a form](#translate-a-form).

**Where should the form script go on BigCommerce?**

Only on the page that shows the form, such as your registration page, and you can load it with `defer`. See [Use SparkLayer Forms on BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce/install.md#use-sparklayer-forms-on-bigcommerce).


---

# Form entries

URL: https://docs.sparklayer.io/help/forms/entries

Review SparkLayer form entries, approve or reject trade applications into a customer group, export entries to CSV, and edit entries or check workflow runs.

> **Quick summary**
>
> - An entry is one submission of a form. To see a form's entries, go to **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)) and click the form's name, or **View entries**. Forms is only in the SparkLayer Dashboard, not in the SparkLayer Wholesale app in Shopify admin.
> - For a trade application, click the applicant, choose their **Customer group**, then click **Approve** or **Reject**. Approving creates the buyer in your store with that group's tag, so they see trade prices when they sign in.
> - **Approve**, **Reject** and the application status run on [workflows](https://docs.sparklayer.io/help/forms/workflows.md), which are on the Growth plan and above (see [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md)). Without them, [approve applications by hand](#approve-an-application-without-workflows).
> - Click **Export** to download a form's entries as a CSV file.
> - You can edit an entry after it's submitted, and each entry keeps a history of its revisions and workflow runs.

## How it works

An entry is created as soon as someone starts filling in a form, with the status **draft**. When the customer submits a valid form, the status changes to **complete**.

To track your own statuses, such as "Awaiting review" or "Approved", add [internal fields](https://docs.sparklayer.io/help/forms/setup.md#add-internal-fields) to the form. The **Wholesale Registration Form** template already has them, and shows each application as **Pending**, **Approved** or **Rejected**.

From application to buyer:

1. **Application submitted**: The entry shows as Pending
2. **You decide**: Choose the customer group, then Approve or Reject
3. **Buyer created**: Approved buyers are added to your store with the group's tag
4. **Buyer signs in**: They see their group's trade prices

Each entry stays linked to the [form version](https://docs.sparklayer.io/help/forms/versions.md) it was created with. Its answers always show in the right structure, even after you change the form.

When a logged-in customer fills in the form, their customer ID is saved with the entry. (A logged-in customer is one synced to SparkLayer and signed in at the time.) You can use the ID in display logic, default values and workflows through [data references](https://docs.sparklayer.io/help/forms/data-references.md#logged-in-sparklayer-customer).

## View entries

1. In the SparkLayer Dashboard, go to **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)).
2. Click the form's name, or **View entries** in its row.

The form's entries screen has **Export** and **Edit form** at the top. For the Wholesale Registration Form, the table shows each entry's **Applicant** (with their company), **Email**, **Country**, **Submitted** date and **Status**.

**More detail**

- Search by name, company or email.
- A dot (●) before a name means the entry is unread, when [read/unread tracking](https://docs.sparklayer.io/help/forms/setup.md#configure-form-settings) is on. The **Unread** column on the Forms screen counts them, for example "2 new".
- When applications are waiting, a banner says how many, for example "2 applications waiting for a decision".
- No entries yet? On a published form, click **Add it to your store** to get the embed options. On a draft form, publish it first.

## Approve or reject an application

1. Open the form's entries and click the applicant's name.
2. Check their company, email and country.
3. Under **Your decision**, choose the **Customer group** they should join. Each group shows its price list, for example "Trade · Trade 20%".
4. Tick **Tax exempt** if the buyer shouldn't pay tax. This sets the Shopify tax exemption on the customer.
5. Click **Approve**, or **Reject** to turn them down.

| Decision | What happens |
| --- | --- |
| **Approve** | The buyer is created as a customer in Shopify with the group's tag, and emailed. They can sign in and see trade prices straight away. |
| **Reject** | The buyer is sent your rejection email. |

The decision runs the form's **Approve/Reject workflow**, which you can change on the **Workflows** tab. See [Form workflows](https://docs.sparklayer.io/help/forms/workflows.md). Once decided, the entry shows its status. If you open it again, you see the decision only.

> **Approve and Reject need workflows**
>
> The **Approve** and **Reject** buttons, the **Application status** and the emails to applicants are all run by workflows, which are on the Growth plan and above (see [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md)). On a plan without workflows, the buttons still show, but clicking them does nothing.

On BigCommerce, approving creates the customer in BigCommerce. See [Use SparkLayer Forms on BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce/install.md#use-sparklayer-forms-on-bigcommerce) for what to check first.

### Approve an application without workflows

On a plan without workflows, review and approve applications by hand:

1. Check the form's **Entries** tab for new applications. No email tells you about them.
2. To approve someone, create them as a customer in your platform. On Shopify, add the customer at **Customers** ([open in the Shopify admin](https://admin.shopify.com/customers)) with the `b2b` tag plus their group's tag, for example `b2b-trade`. See [Assign customers to a customer group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group). Or [invite them](https://docs.sparklayer.io/help/customers/invite-buyers.md) and choose their group.
3. Let the applicant know yourself, whether you approve them or not.

Shopify Flow can't start from a SparkLayer form submission, so you can't automate these steps with Flow.

## Filter entries with views

A view saves which columns the table shows and which filters it applies. You can add as many views as you need, for example an "Awaiting review" view for a registration form.

| View | What it shows |
| --- | --- |
| **Default View** | The **Submitted at** date and time, and the first three fields of each entry. |
| **All Fields** | Every column. Mostly used for exporting entries to CSV. |

To create a view, open the form's entries, click **New view** and choose the columns and filters.

## Export entries

1. Open the form's entries.
2. Click **Export** to download the entries as a CSV file.

## Open an entry

Open an entry to see everything about one submission. Click the entry, and you see:

- Every answer, grouped by page
- The internal fields for your team to fill in
- System metadata (see [Entry metadata](#entry-metadata))
- Workflow activity
- Attached files
- The revision history

### Files and attachments

Files from file upload fields appear in the entry, with their name, type and size. Click a file to preview or download it. Files stay linked to the entry and follow the same permissions. Deleting the entry deletes its files.

## Edit an entry

You can edit an entry after it's submitted, for example to correct a mistake, update account details or continue an internal process.

1. Open the entry.
2. Click **Edit**.
3. Update the fields you need to change.
4. Add a message explaining why you made the edit. We recommend it, as it's kept with the revision.
5. Save your changes.

When you save:

- Validation runs again
- Conditional logic is re-evaluated
- Related workflows may run, depending on how they're set up
- A new revision is recorded

Some fields can't be edited: read-only fields, system-generated values, calculated or derived fields, and locked workflow outputs. A disabled field is controlled by the form's setup or by a workflow.

### Revisions

SparkLayer records every admin edit as a revision. You can see who changed what, restore previous values and follow how workflows updated the entry over time. This helps with onboarding and approval processes, where an entry changes over several steps.

| Revision detail | Example |
| --- | --- |
| **Editor** | An admin or the system. |
| **Timestamp** | When the change happened. |
| **Field updates** | The previous and new values. |

## Delete an entry

On the entries table, click **Delete** on the row. 

> **Deleting an entry is permanent**
>
> Deleting an entry also removes its uploaded files and its workflow history, and can't be undone. Export the entry first if you might need it later.

## Check workflow runs

Each entry keeps a history of the [workflow](https://docs.sparklayer.io/help/forms/workflows.md) runs against it. For each run, you can see when it started, whether it succeeded or failed, how long it took, its logs and each step's output.

You can diagnose most problems this way without a developer. If a workflow fails:

1. Open the failed run.
2. Find the step that failed.
3. Check its input data and error message. The Wholesale Registration Form also shows it in the entry's **Error message** internal field.
4. Correct the entry or the workflow, then run it again.

## Entry metadata

Each entry also stores system information, such as its ID, its form version and when it was submitted.

**Every metadata field**

| Metadata | What it is |
| --- | --- |
| **Entry ID** | The entry's unique identifier. |
| **Entry key** | The key needed to see and edit the entry in the form (the `entry-key` [embed attribute](https://docs.sparklayer.io/help/forms/embedding-and-styling.md#embed-attributes)). |
| **Form version** | The version the entry was submitted with. |
| **Created at** | When the draft entry was created, which is when the customer started filling in the form. |
| **Updated at** | When the entry last changed. |
| **Submitted at** | When the customer submitted the entry. |
| **Status** | The entry's current status, such as **draft** or **complete**. |

## FAQs

**I click Approve and nothing happens**

The **Approve** and **Reject** buttons run workflows, which are on the Growth plan and above. On a plan without them, the buttons do nothing: [approve the application by hand](#approve-an-application-without-workflows). On a plan with workflows, [check the workflow runs](#check-workflow-runs) on the entry to see which step failed.

**Why don't I get an email when someone submits a form?**

Submission emails come from the form's **Notification of submission** workflow. Check it's on the **Workflows** tab and published, and that your plan includes workflows (Growth and above). See [Get notified of new submissions](https://docs.sparklayer.io/help/forms/setup.md#get-notified-of-new-submissions).

**Can Shopify Flow act on a form submission?**

No. Shopify Flow can't start from a SparkLayer form submission. Use the form's own [workflows](https://docs.sparklayer.io/help/forms/workflows.md) instead.

**Approving failed on BigCommerce**

BigCommerce rejects the new customer if one already exists with that email, or if the address is missing a state or region that the country needs (such as Australia). Edit the entry to add the missing details, then approve it again. See [Use SparkLayer Forms on BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce/install.md#use-sparklayer-forms-on-bigcommerce).


---

# Form workflows

URL: https://docs.sparklayer.io/help/forms/workflows

Automate SparkLayer Forms with workflows: run steps such as emails, conditions, API requests and customer creation when an entry is submitted or updated.

> **Quick summary**
>
> - A workflow is an automation that runs when something happens on a form, such as an entry being submitted or an admin clicking an **Approve** button. Typical uses are trade account approvals, internal notifications, order request processing and routing by customer data.
> - You build workflows on a visual canvas, with no code, from the **Workflows** tab of the form builder at **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)). The form templates come with workflows ready to use, such as the **Approve/Reject workflow** on the Wholesale Registration Form. Forms is only in the SparkLayer Dashboard, not in the SparkLayer Wholesale app in Shopify admin.
> - Creating and editing workflows needs the Growth plan or above (see [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md)).
> - Workflows are part of the form version: changes only go live when you [publish](https://docs.sparklayer.io/help/forms/versions.md#publish-changes) the form.

## How it works

Every workflow starts with a **trigger**: the event that starts it. **Steps** follow: the actions it performs. **Connections** (paths) link the steps together on the canvas.

The shape of a workflow:

1. **Trigger**: For example, Form submitted.
2. **Step**: For example, a Condition that checks an answer.
3. **Step**: For example, Create customer.
4. **End**: The workflow run is recorded against the entry.

Steps run one after another, in order (synchronously). While it runs, a workflow can use the entry's answers, the form structure, outputs from earlier steps, and data tables or other stored values. It reads them through [data references](https://docs.sparklayer.io/help/forms/data-references.md).

The **Workflows** tab lists the form's workflows, each with **What it does** and a **Status** (such as **On**). Click **View** to open one. Forms made from a template already have these:

| Workflow | What it does |
| --- | --- |
| **Approve/Reject workflow** | Creates the customer in Shopify with the group's tag and emails them, or sends a polite no. (Wholesale Registration Form) |
| **Prevent duplicate email registrations** | Stops a second application from an email that already has an account. (Wholesale Registration Form) |
| **Notification of submission** | Emails your team when an entry comes in. |

## Example workflows

Most forms need one of these patterns. Build them with the steps in [Create a workflow](#create-a-workflow).

### Approve a trade account application

Add a decision and a button as [internal fields](https://docs.sparklayer.io/help/forms/setup.md#add-internal-fields). The button is a **Workflow trigger button** field. Then run a workflow when your team clicks it:

Approve a trade account application:

1. **Internal button clicked**: Your team approves the entry.
2. **Create customer**: Creates the customer in your store, with their customer group's tag.
3. **Send email**: Tells the customer their account is ready.

The **Wholesale Registration Form** [template](https://docs.sparklayer.io/help/forms.md#start-from-a-template) comes with this set up. Its **Approve/Reject workflow** creates the customer in Shopify with the chosen customer group's tag, so they see trade prices as soon as they sign in. You approve or reject from the entry: see [Approve or reject an application](https://docs.sparklayer.io/help/forms/entries.md#approve-or-reject-an-application).

For a full walkthrough of an approval process, see the [account credit request form](https://docs.sparklayer.io/help/forms/account-credit-request-form.md).

### Notify your team

Email your team about each new entry:

Notify your team:

1. **Form submitted**: Trigger
2. **Send email**: An internal email to your team.

### Route by answer

Send an entry to a different team depending on an answer:

Route by answer:

1. **Form submitted**: Trigger
2. **Condition**: Category equals "Sales"?
3. **Send email**: True path: the sales team. False path: the support team.

### Multi-step approval

Work out a value, record it, then ask for approval only when it's needed:

Multi-step approval:

1. **Form submitted**: Trigger
2. **Calculation**: Work out totals.
3. **Update entry or row**: Write the totals to the entry.
4. **Send email**: Confirm to the customer.
5. **Condition**: If the total is over a threshold, request approval.

### Reset a dependent field

Use this when one field controls the valid options for another. For example, a customer picks a country, and a second field shows that country's regions. If they change the country, the region they chose may no longer be valid, so the workflow clears it.

Reset a dependent field:

1. **Answer updated**: Watching Country.
2. **Clear answer**: Target: Region.
3. **Customer chooses again**: They pick a valid region for the new country.

Other pairs this suits: country and region, customer group and available products, product category and product, department and approval reason, order type and required supporting details.

## Create a workflow

1. Open your form from **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)) and go to the **Workflows** tab.
2. Click **Create workflow**. The canvas opens.
3. To rename the workflow, click the pencil icon next to its name at the top left.

### Add a trigger

1. Click **+ Add Trigger**.
2. Choose the trigger type (see [Triggers](#triggers)).
3. Set its options, for example which answers to watch for **Answer updated**.

### Add steps

1. Click the **+** on a trigger or step, or drag its path handle out onto the canvas. 
2. Choose a step type (see [Steps](#steps)).
3. Set up the step in the panel on the right. Click **Expand** for more room, or **Delete step** to remove it.
4. Connect further steps as needed. Steps with several paths, such as **Condition**, let you branch the workflow.

Click **Arrange steps** to tidy the layout. **Disable** turns the workflow off without deleting it. 

### Publish the workflow

Workflow changes stay in the draft until you publish the form.

1. Check your changes are saved.
2. Click **Publish** and include **Workflows** in what you publish.

Entries created before you publish keep using the workflows from their own version. See [How versions affect entries](https://docs.sparklayer.io/help/forms/versions.md#how-versions-affect-entries).

## Check workflow runs

SparkLayer records a run every time a workflow runs. Check it to see what happened.

1. Open an [entry](https://docs.sparklayer.io/help/forms/entries.md).
2. Go to **Workflow Runs**.
3. Select a run to see its details.

| Detail | What it shows |
| --- | --- |
| **Start and end time** | When the run happened. |
| **Duration** | How long it took. |
| **Status** | Completed or failed. |
| **Step logs** | Each step's inputs, outputs and results. |

### Debug a workflow

1. Open the workflow run.
2. Review each step. You can see exactly which path the run took, including conditional branches.
3. Check error messages and conditions that weren't met.
4. Fix the workflow or the entry data.

## Triggers

| Trigger | Runs the workflow when |
| --- | --- |
| **Form submitted** | A form is completed and submitted. |
| **Entry created** | A new entry is created, which is when someone starts filling in the form. |
| **Answer updated** | One or more selected answers change. |
| **Internal field updated** | One or more selected internal fields change. |
| **Page loaded** | A selected form page loads. |
| **Button clicked** | A button field on the form is clicked. |
| **Internal button clicked** | An admin clicks a button in the internal fields. |
| **API request** | It's called by an API request. |

For example: send an internal notification when a form is submitted, recalculate a value when an answer changes, start an approval when an admin clicks an internal button, update internal fields when review data changes, or start a workflow from another system with an API request.

## Steps

| Step | What it does |
| --- | --- |
| **Send email** | Sends an email to one or more recipients. |
| **Condition** | Branches the workflow based on rules. |
| **Calculation** | Calculates values using numbers, formulas and data references. |
| **For each loop** | Repeats a set of steps for each item in a list, such as line items, repeatable fields or data table rows. |
| **Update entry or row** | Updates a field on a form entry or a data table row. |
| **Clear answer** | Clears one or more values from a form entry or data table row, for example when related data changes. |
| **Read/Unread entry** | Marks an entry as read or unread. |
| **Create entry or row** | Creates a form entry or data table row. |
| **Delete entry or row** | Deletes a form entry or data table row. |
| **API request** | Sends data to another system, such as your ERP or CRM. Usually set up by a developer. |
| **Get customer** | Finds an existing SparkLayer customer by ID, platform ID or email. |
| **Create customer** | Creates a customer in your eCommerce platform and SparkLayer. |
| **Update customer** | Updates an existing SparkLayer customer. |

### Choose the right step

| Step | Use it when |
| --- | --- |
| **Condition** | The workflow needs to make a decision. |
| **Calculation** | You need totals, scores, discounts or other numbers. |
| **Update entry or row** | You want to write a value to the current entry, an internal field, another form's entry or a data table row. |
| **Clear answer** | A previous value is no longer valid, such as a selected option after the field that controls its options changes. |
| **For each loop** | You need to process every item in a list, such as repeatable fields, line items or filtered data table rows. |
| **API request** | Another system needs the form or workflow data. |
| **Get customer**, **Create customer**, **Update customer** | You need to find, create or update customer accounts. |

### Step paths

Some steps have more than one path out. The path decides what happens next.

| Step | Paths |
| --- | --- |
| **Condition** | True, False |
| **For each loop** | Loop body (for each item), After loop |
| **API request** | Success, Error |
| **Get customer** | Found, Not found, Error |
| **Create customer** | Success, Error |
| **Update customer** | Success, Error |
| Most other steps | Next |

For example, an API request continues on the **Success** path if the request works, or follows the **Error** path if it fails.

## The workflow canvas

You build a workflow by placing and connecting nodes on the canvas.

| Action | How |
| --- | --- |
| **Pan** | Click and drag the canvas. |
| **Zoom** | Scroll, or use the zoom controls at the bottom left. |
| **Select a node** | Click it. |
| **Select several nodes** | Shift-click, or drag. |

Triggers and steps appear as nodes, joined by connections. Click a node to edit its settings, see its input and output data, delete it or reconnect it. To connect steps, drag from one node to another. A step can branch into several paths:

| Path | Meaning |
| --- | --- |
| **Next** | Continue to the next step. |
| **True / False** | Conditional branching. |
| **Error** | Runs when a step fails. |
| **Loop** | Used in repeated processes. |

## Tips

- Keep each workflow to one process, and name it clearly. Don't combine unrelated automations.
- Before publishing, use the **Preview** tab, submit test entries and check the workflow runs for errors.
- Plan for errors: add **Error** paths where needed, log important outputs, and protect critical workflows.
- Avoid unnecessary API calls and very long chains of steps.


---

# Data references

URL: https://docs.sparklayer.io/help/forms/data-references

Use data references in SparkLayer Forms to pull answers, logged-in customer data, customer groups, purchases and data tables into logic, options and templates.

> **Quick summary**
>
> - A data reference points to data that already exists, such as another answer, the logged-in customer, their purchases or a data table, instead of a fixed value you type. Simple forms don't need them. They're for forms that react to who's filling them in, or that reuse data you already have.
> - You add one with the **Reference** button (or **+ Reference** in text templates) in the form builder at **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)). It opens the **Select a reference** picker, so you don't need to type reference paths. Forms is only in the SparkLayer Dashboard, not in the SparkLayer Wholesale app in Shopify admin.
> - References work in display logic, validation, default values, option lists, workflow steps, emails and API requests.
> - On customer-facing forms, always filter lists such as purchases to the current customer.

## How it works

The most common uses of data references are:

- Pre-filling a field, such as the signed-in customer's email address, as its **Default value**
- Showing a field only to some customers, for example to one customer group, with [display logic](https://docs.sparklayer.io/help/forms/conditional-logic.md)
- Putting the customer's answers into a notification email in a [workflow](https://docs.sparklayer.io/help/forms/workflows.md)

SparkLayer works out a reference's value when the form is viewed, submitted or updated, or when a workflow runs. You can use references in these places:

- Display logic and validation rules
- Default field values
- Options for select, radio and other choice fields
- Workflow conditions and actions
- Emails, API requests and calculations
- Entry views, filters and columns

## Choose a reference

You pick references from the **Select a reference** picker, rather than typing reference paths.

1. Next to a setting that supports references, click **Reference**. In a text template, such as an email's **From Name**, click **+ Reference** under the field.
2. In **Select a reference**, search with **Search within results...**, or browse. Click **Open** on an item to look inside it, or **Select** to use it.
3. The picker starts with common options, such as the form's own fields. For everything else, click **See advanced options**: **Current entry**, **Data Tables**, **Forms** and **SparkLayer**. To go back, click **Return to common options**.

The picker only offers references that fit the setting you're configuring. For example, a workflow calculation shows values you can calculate with, and an option data source shows lists. Items that don't fit are marked **Wrong shape** and can't be selected. That usually means:

- The setting expects one value, but the reference is a list
- The setting expects a list, but the reference is one value
- The type of value isn't compatible with the setting

Text templates also have **+ Condition** and **+ Loop**, and a **Visual** / **Text** switch to see the template as text.

## Common references

Use this table to find the reference you need in the picker:

| What you want to use | Where to find it in the picker |
| --- | --- |
| An answer on the current form | Current entry > Entry answers |
| Admin-only values on an entry | Current entry > Internal fields |
| The logged-in SparkLayer customer | Current entry > Customer |
| Customer group rules and settings | SparkLayer > Customer Groups |
| Store name, email, phone or address | SparkLayer > Store Details |
| Orders and quotes | SparkLayer > Purchases |
| Reusable option lists | Data Tables |
| Entries from another form | Forms |
| A result from an earlier workflow step | Current workflow run |
| The current item in a loop | Current iteration |

## Current entry

The current entry is the form entry being viewed, submitted or processed. You can reference its answers, status, entry ID and internal fields. You can also reference the SparkLayer customer ID and details, the entry's created, updated and submitted dates, and its Dashboard admin URL.

For example: show a field when another answer has a certain value, include answers in an email, send form data to an external API, update an internal status field, or link to the entry in an admin notification.

### Logged-in SparkLayer customer

When a logged-in SparkLayer customer fills in a form, references can use the customer linked to the entry. The form can then respond to who the customer is, not only what they typed. You can reference their:

- First and last name, email address and company name
- SparkLayer customer ID, external ID or accounting ID
- Customer group, customer status and role
- Tax exempt status and discount percentage
- Default billing or shipping address IDs
- Payment on account details, such as credit limit, balance, currency and net terms

For example: show different fields to different customer groups, route entries by customer group, include account details in workflow emails, send customer identifiers to an external system, or apply approval rules for customers with payment on account.

> **The customer must be signed in on your store**
>
> If the form is on a page where the SparkLayer Core Script isn't loaded, or the customer isn't signed in, the entry is created without a customer. The form builder's **Preview** tab has no customer either, so test customer-based forms on your store.

## SparkLayer data

The **SparkLayer** references use wider B2B data from SparkLayer, not only the current form. Depending on where you use them, this includes customer groups and their settings, store details, customers and purchases.

> **Filter customer data on customer-facing forms**
>
> On forms customers fill in, filter references to the right customer. For example, when you use purchases as the options for a select field, filter them by `Entry -> Customer -> ID` so customers only see their own purchases.

### Customer groups and settings

Use these when a form or workflow should follow rules you've already set up in SparkLayer. For example: show fields only to certain groups, check a request against group rules, route approvals by available payment methods, check whether quotes or checkout are turned on, or include group details in a notification.

**What you can reference for a customer group**

A group's slug, name and parent group, and its settings for price lists, address editing, checkout permissions, allowed payment methods, order quantity and total limits, credit limit enforcement, quotes and stock display.

### Store details

Your store's name, email, phone number, website and address. Use them in templates, messages and workflow steps, for example in an email's **From** and **To** fields.

### Purchases

Purchase references give access to SparkLayer purchases, including orders and quotes. For example: route a workflow by purchase or quote status, include totals in emails or API requests, look up a customer's purchases, check payment status or method, or use purchases, packages and line items as options for a select field. See the [account credit request form](https://docs.sparklayer.io/help/forms/account-credit-request-form.md) for a worked example.

**What you can reference for a purchase**

- The purchase type, and purchase and customer identifiers
- Payment method and status, currency and calculated totals
- Quote status and dates
- Shipping and billing addresses
- Line items (quantities, SKUs and totals) and tax lines
- Shipments, with tracking details

## Data tables

[Data tables](https://docs.sparklayer.io/help/forms/data-tables.md) hold reusable lists. Use them as options for select or radio fields, or to look up values in workflows. Typical lists are items, regions or territories, dealer locations, approval rules, discount bands, licence types, industry categories, or mappings from customer group to approval outcome.

For example: fill a product dropdown from a data table, show only active dealer locations, look up a sales region from the selected country, find an approval rule by order value, or use a discount band in a calculation.

## Other forms

Reference entries from another form when information is spread across forms. For example: offer submitted partner records as options in another form, look up a previous application, create a related entry in another form, update a connected record from a workflow, or build internal admin processes across forms.

## Workflow and loop data

Inside a [workflow](https://docs.sparklayer.io/help/forms/workflows.md), references can use calculation results, API request outputs, values created or updated by earlier steps, and the current item, index or item key in a **For each loop**.

For example: calculate a total and write it to the entry, use an API response in a later email, update each line item in a loop, branch on an earlier step's output, or send calculated values to another system.

## Use references in conditions

Display logic, validation rules and workflow **Condition** steps all use conditions. The picker helps you choose compatible values for each side. For example:

- Show **VAT number** when **Country** equals "United Kingdom"
- Require **Trade licence** when **Business type** equals "Licensed trade"
- Continue a workflow only when **Approval status** equals "Approved"
- Apply a discount when **Order total** is greater than 1000
- Route an entry when the customer group equals "Wholesale"

## Use references in templates

Some workflow settings and messages are templates, where you can insert references into text. Use **+ Reference** to insert them, rather than typing reference paths. For example:

- Email subject: New application from \{\{ Customer Name }}
- Email body: Customer email: \{\{ Email }}
- API URL: `https://example.com/customers/{{ Customer ID }}`
- API body: include answers in a JSON payload
- Calculation: use numeric answers to work out totals, discounts or scores

Templates are used in emails, API requests, success messages and workflow calculations.

## Use references as options

Select, radio and similar fields can take their options from a reference, instead of a list you type. This suits options that change often, long lists, and lists used in several places.

1. Select the field and open the **Options** section.
2. Switch from **Manual** to **Data source**.
3. Click **Select data source...** and choose a list in the picker. It shows **Connected** once a source is set.
4. If the source is a list of rows or objects, choose an **Option label field**: the value customers see for each option.

To start again, click **Clear data source**.

When the source is a list of simple values, each value is used as the label.

**What's stored when a customer picks an option**

The option's stored value is always the item's ID, such as a SparkLayer customer or purchase ID, a customer group slug or a repeater instance key.

For example: fill a product dropdown from a data table, list dealer locations matching the customer's group, let admins choose from submitted partner records, or use a repeatable field as the source for another choice field.

## Filter references

You can filter some references before you use them. A filter narrows a list of entries, rows, customers or objects to the records that matter. Filters can use fixed values or other references. For example:

- Only data table rows where "Active" is true
- Products where "Category" equals "Accessories"
- The rule where "Country" equals the customer's selected country
- Form entries whose status is complete
- The first matching row, using one field from it
- Purchases for the entry's customer with a certain payment status

For example, a form asks for the customer's country. A workflow finds the data table row for that country and uses it to assign the right sales region.

Once you add a filter, it's listed under **Active Filters**, where you can **Remove** it. Then choose what to do next:

- **Select this filtered set** uses the list.
- **Add another filter** narrows it further.
- **Clear all filters** starts again.
- **Navigate into filtered set** picks a value from inside it.

The operators available depend on the field you filter, and include equals, not equals, contains, greater than, less than, is empty, is not empty, is true and is false.

## Lists and single values

If you can't select a reference, check what the setting expects. Some settings need one value, and others need a list.

Settings that need one value include an email address, a customer name, a number for a calculation, a field to update, the first matching data table row or a customer group name.

Settings that need a list include rows used as options, items in a repeatable group, entries for a **For each loop**, a filtered set of data table rows or purchase line items.

## Format values

In workflow templates, formatters change a value before it's used, for example to show "Not provided" when an answer is empty.

**Every formatter**

| Formatter | What it does |
| --- | --- |
| **Set fallback value** | Uses this value if the reference is empty, for example "Not provided". |
| **Convert to uppercase** / **Convert to lowercase** | Changes the case of text. |
| **Capitalize first letter** | Capitalises the first character. |
| **Truncate to N words** / **Truncate to N characters** | Shortens text, adding "..." if it was cut. |
| **Format decimal places** | Shows a number to a set number of decimal places. |
| **Convert to yes/no** | Turns true or false into your own text, such as "Active,Inactive". |
| **Format date** | Formats a date or time. The format is written as an example date (a Go layout): `2006-01-02` gives YYYY-MM-DD, and `02/01/2006` gives DD/MM/YYYY. |

Formatters can also join a list into one line of text (such as tags as a comma-separated list), extract one field from each item in a list, count items (such as line items) and format numbers.

## Tips

- Use data tables for long or reusable option lists.
- Use customer references when logic depends on who's filling in the form, rather than asking customers to re-enter what SparkLayer already knows.
- Use SparkLayer references when logic depends on customer groups, settings, purchases, quotes or store data.
- Filter references to keep them specific. A filtered reference is usually safer than a whole list.
- Test with real examples: empty values, unexpected values, different customer groups and several entries. Test on the **Preview** tab, and above all on your store, signed in with the kind of customer account (or none) your customers will use.


---

# Data tables

URL: https://docs.sparklayer.io/help/forms/data-tables

Keep reusable lists in SparkLayer Forms data tables, import rows from CSV and use them as options for choice fields or as lookup data in workflows.

> **Quick summary**
>
> - A data table is a simple spreadsheet inside Forms: columns define the data, rows hold the records, and views filter rows and choose columns.
> - Columns can be **Text**, **Number** or **Date**. You can add rows by hand, import them from CSV and export them to CSV.
> - Use a data table as the options for a select, radio or multiple choice field. You can also look up its rows in calculations, conditions and workflows.
> - Data tables have their own screen under Forms, at **Forms > Data tables** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms/tables)). Like Forms, they're only in the SparkLayer Dashboard, not in the SparkLayer Wholesale app in Shopify admin.

## How it works

A data table keeps a list in one place, so several forms can use it and you only update it once. Use one when you want to:

- Fill select, radio or multiple choice fields from a central list
- Reuse the same data across forms
- Look up rows and values in calculations, conditions and workflow logic
- Keep form logic simpler by managing data in one place

Common examples include:

| Table | What it's for |
| --- | --- |
| **Sales territories** | Postcodes to reps, so new applicants land with the right agent. |
| **Approved tax numbers** | Check a buyer's VAT number during registration. |
| **Stockists** | Your retailers, for a store finder or approval checks. |

Others include product lists, branch or store locations, pricing bands, internal reference codes, and approved option lists for advanced forms.

## Create a data table

1. In the SparkLayer Dashboard, go to **Forms > Data tables** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms/tables)) and click **Create table**.
2. Name the table, then add the columns you need, choosing **Text**, **Number** or **Date** for each.
3. Add rows by hand, or import them from a CSV file.

You can export the table's rows to CSV at any time.

Once your table is ready, use it in a form.

## Use a data table in a form

### As options for a choice field

Fill a select, radio or multiple choice field from the table, instead of typing the options:

1. Select the field and open **Options**.
2. Switch to **Data source** and click **Select data source...**.
3. In the reference picker, open **Data Tables** and select your table.
4. Choose the column to show as the **Option label field**.

See [Use references as options](https://docs.sparklayer.io/help/forms/data-references.md#use-references-as-options).

### As lookup data

In a workflow calculation, condition or other step, reference the table. Then [filter](https://docs.sparklayer.io/help/forms/data-references.md#filter-references) it to the rows you need, for example the row for the customer's country.

## Example: a products table

A form asks customers which products they want samples of. Instead of typing the product list into the field, keep it in a data table:

1. Create a **Products** data table with columns for product name, SKU, category and price.
2. Add a row for each product, or import them from a CSV file.
3. On the form, add a **Multiple choice** field and set its options to the **Products** table, with the product name as the **Option label field**.

When your range changes, update the table once, and every form that uses it shows the new list. You can use the same rows later in workflow logic or calculations.

## Next steps

- [Data references](https://docs.sparklayer.io/help/forms/data-references.md): Use data table rows as field options and look them up in workflows
- [Field types](https://docs.sparklayer.io/help/forms/field-types.md): The choice fields that can take their options from a data table
- [Form workflows](https://docs.sparklayer.io/help/forms/workflows.md): Use your table data in calculations, conditions and other steps


---

# Account credit request form

URL: https://docs.sparklayer.io/help/forms/account-credit-request-form

Build an account credit request form in SparkLayer Forms: customers pick a purchase and line items, give reasons and upload photos for your team to approve.

> **Quick summary**
>
> - This worked example builds a form where logged-in B2B customers request credit for items from a recent purchase. Reasons include damaged, missing or incorrect items, and quality or pricing issues.
> - You build it at **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)) using a repeatable group, purchase data references, display logic, internal fields and workflows. Forms is only in the SparkLayer Dashboard, not in the SparkLayer Wholesale app in Shopify admin.
> - It relies on the logged-in customer, so test it on your store, not on the **Preview** tab.
> - The approval and decline automations need the Growth plan or above, as they use [workflows](https://docs.sparklayer.io/help/forms/workflows.md).

## What you'll build

Customers will:

1. Select a recent purchase.
2. Add one or more line items they want credit for.
3. Choose a reason for each line item.
4. Give extra details depending on the reason.
5. Upload photos or supporting files.
6. Submit the request for review.

Your team can then:

- Track the request's status and assign it to someone
- Approve or decline it, and record the approved credit amount
- Add internal notes
- Run actions when a request is approved or declined

## How it works

The credit request process:

1. **Customer picks items**: They choose a purchase, then each affected line item and a reason.
2. **Adds evidence**: Extra fields appear for the reason; they upload photos or files.
3. **Submits**: The request arrives as an entry and your team is notified.
4. **Team reviews**: Reviewers update internal fields and decide.
5. **Workflow acts**: Approve or decline: email the customer or send it to another system.

You can start simple, by collecting requests and notifying your team. Add automation later, such as approval buttons, applying credit to the customer's account automatically on approval, and sending data to other systems.

## Before you start

This form works best when customers are signed in before they open it. SparkLayer can then identify the customer and use their customer, purchase and customer group data.

Before you build, decide:

- **Which purchases** customers can choose from (which purchase or order data).
- **Which credit reasons** you support.
- **What evidence** each reason needs.
- **Who reviews** requests.
- **Whether customers get a confirmation** email.
- **What happens after approval or decline**, for example sending the request to your ERP, helpdesk, finance system or support team.

> **Test on your store, not in Preview**
>
> The form shows each customer their own purchases, so it needs a logged-in customer. The **Preview** tab has no customer, so it can't show the purchase options. Embed the form on a page of your store where the SparkLayer Core Script is loaded, and test it there. The page can be private or hidden at first.

## Create the form

1. In the SparkLayer Dashboard, go to **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)) and click **Start with a blank form**.
2. On the **Settings** tab, enter the **Form title** "Account Credit Request" and click **Save** in the save bar.
3. Go back to the **Form** tab to add fields.

## Add the customer fields

The customer fills in these fields. On the **Form** tab, add:

| Field | Type | Notes |
| --- | --- | --- |
| **Purchase** | Select | The purchase the request relates to. Required. |
| **Credit request items** | Group, with **Repeatable** on | Lets customers add several line items. Holds the fields below. |
| **Reason category** | Radio (or Select) | Inside the group. For example: Damaged, Missing, Incorrect item, Quality issue, Pricing issue, Other. Required. |
| **Line item** | Select | Inside the group. Options come from the selected purchase. Required. |
| **Quantity affected** | Number | Inside the group. Useful when only part of a line item needs credit. Required. |
| **Reason for credit request** | Long text | Inside the group. Lets the customer explain the issue. Required. |
| **Supporting files** | File upload | Inside the group. Photos, delivery notes or other evidence. |
| **Preferred resolution** | Radio (or Select) | Inside the group. Optional. For example: Credit note, Replacement, Contact me. |

To set up the repeatable group:

1. Add a **Group** field and name it **Credit request items**.
2. On its **Properties** tab, turn on **Repeatable**, so customers can add the group more than once.
3. Add the reason, line item, quantity, description, file upload and resolution fields inside the group.

A repeatable group suits this form because one purchase can have several items that need credit.

## Show the customer's purchases as options

The **Purchase** field takes its options from the customer's purchases, not from a list you type.

1. Select the **Purchase** field.
2. In **Options**, switch from **Manual** to **Data source**.
3. Click **Select data source...**. In the **Select a reference** picker, click **See advanced options** to see every source, not only the form's fields.
4. Open **SparkLayer** > **Purchasing** and click **Select** on **Entry Customer's Purchases** (the purchases for the SparkLayer customer associated with this entry).
5. Click the **Option label field** reference and choose a clear label, such as **Purchase Identifiers** > **Visible ID**.

**Entry Customer's Purchases** is already filtered to the signed-in customer. Don't use **Store's Purchases**, which lists orders from all customers.

## Show the purchase's line items as options

The **Line item** field then lists the items in the purchase the customer picked.

1. Select the **Line item** field inside the group.
2. In **Options**, switch to **Data source** and click **Select data source...**, then **See advanced options**.
3. Open **SparkLayer** > **Purchasing**.
4. Under **Specific Purchase by SparkLayer ID**, click **Reference** and **Select** your **Purchase** field.
5. Scroll down and click **Select** on **All Packages' Line Items** (line items from every package in this purchase).
6. Click the **Option label field** reference and choose a clear label, such as **Line item Identifiers** > **SKU**.

## Show extra questions for each reason (optional)

Use display logic so customers only see the fields that matter for their reason:

| Reason | Extra fields to show |
| --- | --- |
| Damaged item | Photo upload, damage description |
| Missing item | Missing quantity, delivery note upload |
| Incorrect item received | Expected item, item received, photo upload |
| Quality issue | Description, photo upload |
| Pricing issue | Expected price, explanation |
| Other | General explanation |

For example, to show **Supporting files** only for damaged items:

1. Select the **Supporting files** field.
2. Open the **Display logic** tab.
3. Under **Conditional display logic**, set **Field** to **Credit request items** > **Reason category**.
4. Set **Condition** to **Equals** and **Value** to `damaged`.

See [Conditional logic](https://docs.sparklayer.io/help/forms/conditional-logic.md) for more.

## Add validation

Check each request is complete before it reaches your team:

| Field | Validation |
| --- | --- |
| Purchase | Required |
| Line item | Required |
| Reason category | Required |
| Quantity affected | Required, greater than 0 |
| Reason for credit request | Required for "Other" or complex reasons |
| Supporting files | Required for damaged or quality issue requests |

Most fields only need to be required. Select the field and tick **Required** under **Basic properties** on the **Properties** tab. For anything more, such as "greater than 0", use the **Validation** tab. See [Validation rules](https://docs.sparklayer.io/help/forms/validation.md).

## Add internal review fields (optional)

To manage the review in SparkLayer, add [internal fields](https://docs.sparklayer.io/help/forms/setup.md#add-internal-fields): fields only your team sees, next to each entry in the Dashboard. Customers never see them. If you review credit requests in your ERP or another system, you may not need this.

On the **Internal fields** tab, add fields such as:

| Internal field | Type | Purpose |
| --- | --- | --- |
| **Review status** | Select | New, In review, Approved, Declined, Actioned. |
| **Assigned to** | Text or Select | Who's handling the request. |
| **Decision** | Select | Approved or declined. |
| **Approved credit amount** | Number | The amount the reviewer approves. |
| **Reviewer notes** | Long text | Internal comments. |
| **External reference ID** | Text | A ticket, ERP or finance system reference. |
| **Approve** button | Workflow trigger button | Starts the approval workflow. |
| **Decline** button | Workflow trigger button | Optional. Starts a decline workflow. |

This keeps the customer's form short while giving your team a structured place to record the review.

## Review a request

When a customer submits the form, the request appears as an [entry](https://docs.sparklayer.io/help/forms/entries.md). Your team opens it, reviews the answers and uploaded files, and updates the internal fields. A typical review:

1. Set **Review status** to **In review**.
2. Add reviewer notes.
3. Set a decision.
4. If approved, enter the approved credit amount.
5. Click **Approve** or **Decline**. A workflow handles the next action.

## Notify your team on submission

Add a workflow that emails your team for every new submission:

1. On the **Workflows** tab, click **Create workflow**.
2. Add the **Form submitted** trigger.
3. Add a **Send email** step to your team's address.

Forms made from a template already have one, called **Notification of submission**.

## Send the customer a confirmation (optional)

To email the customer as well, add a second **Send email** step to that workflow on the **Workflows** tab. See [Form workflows](https://docs.sparklayer.io/help/forms/workflows.md).

## Clear line items when the purchase changes (optional)

The line item options depend on the selected purchase. If a customer picks a purchase, chooses line items, then changes the purchase, the old line items stay selected. A workflow can clear them.

1. On the **Workflows** tab, add a workflow and name it "Reset credit items when purchase changes".
2. Click **+ Add Trigger**, choose **Answer updated** and set it to watch the **Purchase** field.
3. Add a **Clear answer** step and set its **Target reference** to **Credit request items**.

Reset credit items when purchase changes:

1. **Answer updated**: Watching Purchase.
2. **Clear answer**: Target: Credit request items.
3. **Customer chooses again**: They pick line items from the new purchase.

This is a good example of using a workflow to keep dependent fields accurate (see [Reset a dependent field](https://docs.sparklayer.io/help/forms/workflows.md#reset-a-dependent-field)).

## Approve requests

After review, a workflow can handle the next action, for example sending the approved request to another system, emailing the customer and updating the entry's status. Create a workflow called "Credit request approved". Use either the **Approve** button or the **Review status** field as the trigger.

### Option A: an internal button

| Part | Value |
| --- | --- |
| Trigger | **Internal button clicked**, on the **Approve** button |
| Step 1 | **Condition** |
| Step 2 | **API request** or **Send email** |
| Step 3 | **Update entry or row** |

### Option B: a status field

| Part | Value |
| --- | --- |
| Trigger | **Internal field updated**, watching **Review status** |
| Condition | **Review status** equals "Approved" |
| Step 1 | **API request** or **Send email** |
| Step 2 | **Update entry or row** |

### Common approval actions

Whichever trigger you use, the workflow can:

- Send the approved request to an ERP or finance system with an **API request** step
- Create a support ticket by calling an external API
- Email the customer
- Set **Review status** to "Actioned"
- Update the customer record with an **Update customer** step

## Decline requests

For a structured decline process, create a second workflow called "Credit request declined".

| Part | Value |
| --- | --- |
| Trigger | **Internal button clicked** (the **Decline** button), or **Internal field updated** |
| Condition | **Decision** equals "Declined" |
| Step 1 | **Send email** |
| Step 2 | **Update entry or row** |

Common decline actions are emailing the customer, setting **Review status** to "Declined", adding an internal note and storing the date the request was declined.

Keep the customer's message short and clear. If the request needs a personal explanation, ask the reviewer to write an internal note, and include it in the email.

## Send approved requests to another system (optional)

If your finance, ERP, helpdesk or support system accepts API requests, add an **API request** step after approval. A developer usually sets this step up, as they know what data your other system expects. The request can include:

- Customer details
- Purchase or order details
- The requested line items and reasons
- Uploaded file references
- The approved amount and reviewer notes
- A link to the entry
- The external reference ID

Build the request body in the template editor. Insert values with **+ Reference** rather than typing reference paths (see [Data references](https://docs.sparklayer.io/help/forms/data-references.md)). Use **+ Loop** to output each item in the **Credit request items** group, and **+ Condition** for conditional content.

**Example JSON template for your developer**

Here's an example JSON template. Your field IDs and the fields your system expects will differ:

```json
{
    "purchase_id": "{{sparklayer:purchases.purchases[purchase_identifiers.sparklayer={entry:current.answers.order_id}][0].purchase_identifiers.platform}}",
    "returns": [{% for item in {{entry:current.answers.returns}} %}
        {
            "sku": "{{item.sku}}",
            "quantity": "{{item.quantity}}",
            "reason": "{{item.reason}}",
            "images": [{% for img in item.images %}"{{img}}"{% if not forloop.Last %},{% endif %}{% endfor %}]
        }{% if not forloop.Last %},{% endif %}
{% endfor %}]
}
```

Each uploaded file's value is a SparkLayer file ID. Your system can fetch the files securely with the [Files API](https://docs.sparklayer.io/developers/api/files/get-bulk-files.md).

## Publish, embed and test

1. When the form, internal fields and workflows are ready, click **Publish** and include all three (see [Versions and publishing](https://docs.sparklayer.io/help/forms/versions.md)).
2. Decide where customers will find the form: on an account page, linked from an order or support page, or shared as a link with selected customers.
3. Add the form to your store with the options on the **Embed** tab. Use a page where the SparkLayer Core Script is loaded, and where customers can sign in and see the SparkLayer account and cart widgets. See [Embed and style a form](https://docs.sparklayer.io/help/forms/embedding-and-styling.md).

The **Preview** tab is less useful for this form, because it has no logged-in customer. For this and any other advanced form, test on your store.

### Testing checklist

- A **logged-in customer** can open the form.
- The **Purchase** field shows the expected purchases.
- The **Line item** field shows the selected purchase's line items.
- **Changing the purchase** clears previously selected line items.
- **Reason-specific fields** show and hide correctly.
- **Required fields** stop incomplete submissions.
- **File uploads** work.
- A submitted request **appears as an entry**.
- The right **internal fields** appear next to entries.
- **Submission notification** emails are sent.
- **Approval and decline workflows** run correctly.
- **API requests** send the expected data, if you use them.

If you use customer-specific purchase data, test with more than one customer account.

## Tips

- Keep the customer's form short: the purchase, affected line items, reason and evidence.
- Use a repeatable group for line items, so customers don't submit a separate form for each item.
- Use display logic for reason-specific questions, so extra fields only appear when needed.
- Use file uploads for evidence. Photos help most with damaged or quality-related requests.
- Keep admin-only statuses, notes and decisions in internal fields, never on the customer's form.
- Clear dependent fields when the field they depend on changes.
- Use workflows for notifications, approvals, API requests, status updates and other repeatable admin steps.
- Start simple: launch with manual review, then add API integrations later.
- Test with real customer accounts to check purchases and line items show as expected.


---

# Find your way around SparkLayer

URL: https://docs.sparklayer.io/help/dashboard

A tour of the SparkLayer Dashboard and the SparkLayer apps in Shopify and Wix: the menus, what Home shows, and where older screens moved to.

> **Quick summary**
>
> - SparkLayer comes in 3 versions with the same screens. The **SparkLayer Dashboard** at [app.sparklayer.io](https://app.sparklayer.io/) has a grouped sidebar. The **Shopify app**, **SparkLayer Wholesale** under **Sales channels** in your Shopify admin, has one menu item per area, with that area's pages as tabs. On Wix, you can also manage SparkLayer in the **Wix app**, inside your Wix dashboard.
> - Pick your version with the **Steps for** switch under each page title in these docs. Every path, such as **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app, then shows the menus you'll see.
> - **Home** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale** in the Shopify app is where you start. Check this week's wholesale sales and pick up your setup, plan and store status.
> - Forms and Data tables are only in the SparkLayer Dashboard. The Shopify app has its own **Setup**, **Try it out** and **Plan** menu items. Looking for a screen from an older guide? See [Where things moved](#where-things-moved).

## Three versions of the same app

Manage SparkLayer in whichever version suits you. They have the same screens and work on the same SparkLayer account.

- **SparkLayer Dashboard**: sign in at [app.sparklayer.io](https://app.sparklayer.io/). Areas are groups in the sidebar, and each page has its own menu item.
- **Shopify app**: in your Shopify admin, open **SparkLayer Wholesale** under **Sales channels**. Each area is one menu item, and its pages are tabs under the page title.
- **Wix app**: in your Wix dashboard, open **SparkLayer B2B & Wholesale** under **Apps**. These docs show the SparkLayer Dashboard's paths for Wix.

These docs show the path for the version you pick with **Steps for**, under the page title. Your choice is remembered on every page.

Here are the menus in the SparkLayer Dashboard and the Shopify app.

**SparkLayer Dashboard (sidebar)**

- **Home**
- **Orders**
- **Pricing**: Price lists, Price editor, Discounts, Products
- **Customers**: Companies, Customers, Groups
- **Sales agents**: Sales agents, Roles
- **Forms**: Forms, Data tables
- **Integrations**: Platform, Partners
- **Storefront**: Widgets, Options
- **Settings**: Configurations, Shipping, API, Templates
- At the foot: **Help**, **Explore features** and your plan card

**Shopify app (SparkLayer Wholesale)**

- **SparkLayer Wholesale** (opens Home)
- **Setup**
- **Try it out**
- **Orders**
- **Pricing**: tabs Price lists, Price editor, Discounts
- **Customers**: tabs Companies, Customers, Customer groups
- **Sales agents**: tabs Sales agents, Roles
- **Storefront**: tabs Widgets, Options
- **Integrations**: tabs Platform, Partners, Product sync
- **Explore features**
- **Settings**: tabs Configurations, Shipping, API, Templates
- **Plan** (opens the plans window)

**Small differences between the SparkLayer Dashboard and the Shopify app**

- **Setup** and **Try it out** have no sidebar item in the SparkLayer Dashboard. Open Setup from Home (**Open Setup**), and Try it out from Orders before your first order (**Place a test order**).
- The Dashboard calls customer groups **Groups** in the sidebar. The Shopify app's tab says **Customer groups**.
- Page titles differ on areas with tabs. In the Dashboard the title is the page, such as **Configurations**. In the Shopify app it's the area, such as **Settings**, with the page as a tab.
- Only the Dashboard has a switcher at the top of the sidebar, to change between your SparkLayer accounts and stores. See [Create a new team](https://docs.sparklayer.io/help/dashboard/account.md#create-a-new-team).

## What each area is for

Each area of the app covers one part of your B2B setup.

| Area | What you do there | Learn more |
| --- | --- | --- |
| **Home** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale** in the Shopify app | See this week's sales and pick up setup, plan and store status. | [Home](#home) |
| **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app | The five steps to get your first wholesale order, including [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md). | [Get started](https://docs.sparklayer.io/help/get-started.md) |
| **Orders > Place a test order** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Try it out** in the Shopify app | Place a test order as a buyer. | [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order) |
| **Orders** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/activity)), or **SparkLayer Wholesale > Orders** in the Shopify app | See B2B orders placed through SparkLayer, and your sales compared with the period before. | [Orders](https://docs.sparklayer.io/help/dashboard/orders.md) |
| **Pricing** | Manage your [price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md), edit single prices in the [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md), set up [discounts](https://docs.sparklayer.io/help/pricing/discounts.md) and check your [products are syncing](https://docs.sparklayer.io/help/integrations/data-sync.md). | [Pricing](https://docs.sparklayer.io/help/pricing.md) |
| **Customers** | Your [customers](https://docs.sparklayer.io/help/customers/managing-customers.md), [companies](https://docs.sparklayer.io/help/customers/companies.md) and [customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md): who buys from you and the rules they buy under. | [Customers](https://docs.sparklayer.io/help/customers.md) |
| **Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app | Make someone a sales agent, choose their customers and set what their [role](https://docs.sparklayer.io/help/sales-reps.md) lets them do. Starter plan and above. | [Sales rep setup](https://docs.sparklayer.io/help/sales-reps.md) |
| **Forms** | Wholesale registration and other forms, and the data tables they use. SparkLayer Dashboard only. | [Forms](https://docs.sparklayer.io/help/forms.md) |
| **Integrations** | Your [platform](https://docs.sparklayer.io/help/integrations/managing-integrations.md) connection and Shopify order actions, and [partner apps](https://docs.sparklayer.io/help/integrations.md). | [Integrations](https://docs.sparklayer.io/help/integrations.md) |
| **Storefront** | Add SparkLayer to your theme in **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app, and choose how the storefront looks and behaves in **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app. | [Storefront](https://docs.sparklayer.io/help/storefront.md) |
| **Settings** | Store-wide settings, shipping, API keys and templates. | [Settings](https://docs.sparklayer.io/help/dashboard/settings.md) |
| **Explore features** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Explore features** in the Shopify app | Browse what SparkLayer can do, and preview paid features before you upgrade. | [Explore features](https://docs.sparklayer.io/help/dashboard/plan-and-features.md#explore-features) |
| **Plan card** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Plan** in the Shopify app | Your plan, this month's usage and the plans to choose from. | [Your plan](https://docs.sparklayer.io/help/dashboard/plan-and-features.md) |

## Home

### This week's numbers

The strip at the top shows the last 7 days. Each figure shows its change from the 7 days before:

| Figure | What it shows |
| --- | --- |
| **Wholesale sales** | The total of your B2B orders. |
| **Orders** | How many B2B orders were placed. |
| **Average order** | The average value of a B2B order. |
| **Active buyers** | How many buyers placed an order. |

Click the strip to open **Wholesale sales**, with a chart and filters for the last 7, 30 or 90 days. From there, click **View all orders** to go to [Orders](https://docs.sparklayer.io/help/dashboard/orders.md).

Beside the strip, **Sales agents** shows how many of your plan's agents you use. **Companies** shows how many businesses you sell to.

Before your first order, the strip says **No orders yet**.

### The cards below

Cards appear when they're useful. You can minimise most of them and dismiss some, and they stay that way when you come back.

| Card | When you see it | What it does |
| --- | --- | --- |
| **Get your first wholesale order** | Before your first order. | Shows your setup progress and the next step, with **Open Setup**. See [Get started](https://docs.sparklayer.io/help/get-started.md). |
| **Your first wholesale order is in** | Once, when your first order arrives. | Shows the order, with **View the order**. |
| **Get live with SparkLayer** | After your first order, until every setup step is done. | The same steps as Setup. |
| **Your SparkLayer briefing** | After your first order. | Up to 3 things to review, each with a button to fix it. For example, an order waiting for you, a customer group with no price list or customers that didn't sync. On paid plans, it also shows this month's B2B sales and the time SparkLayer saved you. |
| Plan card, such as **Basic plan** | Always (starts minimised). | Your plan and this month's usage. See [Your plan](https://docs.sparklayer.io/help/dashboard/plan-and-features.md#your-plan). |
| **Store status** | Always (starts minimised). | Whether SparkLayer is live on your theme, with **Open theme setup**. See [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md). |
| **Get more from SparkLayer** | On plans without every feature. | Paid features you can preview before you upgrade. On Pro, **Your SparkLayer features** lists what's included. |
| **Helpful while you set up** | Always. | Guides, FAQs and a free plan review. On paid plans it's called **Help and resources**. |

Prefer us to set it up for you? Click **Book free setup** at the foot of Home to book our onboarding team.

## Your plan

Your plan and this month's usage are always one click away.

- **SparkLayer Dashboard**: the plan card at the foot of the sidebar shows your plan, a badge such as **Active** or **Nearly full**, and meters for **B2B orders this month**, **Price lists** and **Sales agents**.
- **Shopify app**: **Plan** in the menu opens the plans window.

Both also show on Home, in the plan card. See [Your plan and usage](https://docs.sparklayer.io/help/dashboard/plan-and-features.md), and for how you're billed, trials and cancelling, [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md).

## Live data and test mode

The Dashboard works on your live store, and the SparkLayer Dashboard's top bar shows a **Live Data** pill. On the Pro and Enterprise plans, the **Test mode** switch moves the Dashboard to your test store instead: see [Test mode](https://docs.sparklayer.io/help/dashboard/test-mode.md).

## Where things moved

If you used SparkLayer before the new app, or you're following an older guide, this is where things are now.

| You're looking for | It's now |
| --- | --- |
| **Activity** | **Orders** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/activity)), or **SparkLayer Wholesale > Orders** in the Shopify app. See [Orders](https://docs.sparklayer.io/help/dashboard/orders.md). |
| Onboarding steps on Home | **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app. See [Get started](https://docs.sparklayer.io/help/get-started.md). |
| **Customer groups** and **Sales Agents** as menu items of their own | Customer groups are at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app, and sales agents at **Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app. |
| **Settings > General** | **Settings > Configurations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations** in the Shopify app. See [Settings](https://docs.sparklayer.io/help/dashboard/settings.md#configurations). |
| **Settings > Frontend widgets** | **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app to add SparkLayer to your theme, and **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app for how it looks and behaves. |
| **Settings > API keys** | **Settings > API** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/api)), or **SparkLayer Wholesale > Settings > API** in the Shopify app. |
| **Integrations > Platform Connection** | **Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app. |
| **Auto-complete Shopify draft orders** | **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app. |
| **Integrations > Partner Integrations** | **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app. |
| **Integrations > Data Sync** | **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app for products. Customer sync errors show as a banner on **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app. See [Product and customer sync](https://docs.sparklayer.io/help/integrations/data-sync.md). |
| **Customer Data Lookup** | Search for the customer at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app and open their page. See [Find and manage customers](https://docs.sparklayer.io/help/customers/managing-customers.md). |
| **Account > Plan** | The plan card at the foot of the SparkLayer Dashboard's sidebar, or **Plan** in the Shopify app. See [Your plan](https://docs.sparklayer.io/help/dashboard/plan-and-features.md). |
| The **Test mode** switch | Still there on the Pro and Enterprise plans. See [Live data and test mode](#live-data-and-test-mode). |
| **SparkLayer B2B & Wholesale** in Shopify admin | The Shopify app is now called **SparkLayer Wholesale**, under **Sales channels**. |

**Shopify only:**

Can't see **Forms** in the Shopify app? Forms and Data tables are only in the SparkLayer Dashboard: sign in at [app.sparklayer.io](https://app.sparklayer.io/). See [Forms](https://docs.sparklayer.io/help/forms.md).

## Related guides

- [Get started](https://docs.sparklayer.io/help/get-started.md): set up SparkLayer and take your first wholesale order.
- [Your account and team](https://docs.sparklayer.io/help/dashboard/account.md): your Site ID, password and team.
- [Your plan and usage](https://docs.sparklayer.io/help/dashboard/plan-and-features.md): your plan, usage, free trials and locked features.
- [Settings](https://docs.sparklayer.io/help/dashboard/settings.md): Configurations, Shipping, API and Templates.


---

# Orders

URL: https://docs.sparklayer.io/help/dashboard/orders

See the B2B orders placed through SparkLayer on the Orders screen: compare sales with the period before, filter by type and open each order in Shopify.

> **Quick summary**
>
> - **Orders** lists the B2B orders placed through SparkLayer, and compares your sales for a period with the period before. Go to **Orders** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/activity)), or **SparkLayer Wholesale > Orders** in the Shopify app.
> - It only counts SparkLayer (B2B) orders, not retail orders placed through your store's own checkout.
> - The top card has the filters, 3 figures (**Orders**, **Total sales** and **Avg. order**) and a chart. **Sales history** below it lists the orders, each linked to the order in Shopify.
> - It's the same data as the sales figures on [Home](https://docs.sparklayer.io/help/dashboard.md#home).

## How it works

When a buyer places an order through the SparkLayer cart and checkout, SparkLayer creates it in your Shopify admin. The order then appears in Orders.

An order that isn't a completed Shopify order yet appears straight away as [Awaiting merchant](https://docs.sparklayer.io/help/glossary.md#awaiting-merchant). Usually it's a Pay on Account or Pay by Invoice order that's still a draft order for you to complete. It has a purchase ID, but no Shopify order yet.

How an order reaches Orders:

1. **Buyer orders**: Through the SparkLayer cart and checkout, at their trade prices.
2. **Order in Shopify**: Created as a completed order, or as a draft order that shows as **Awaiting merchant** until you complete it.
3. **Shows in Orders**: Counted in the figures and listed in **Sales history**.

| Order created as | When |
| --- | --- |
| **Draft order** | By default, for manual payment methods: Pay on Account and Pay by Invoice. |
| **Completed order** | For upfront payment by card, or for manual payment methods when **Auto-complete draft orders** is on in **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app. |

**What counts as a SparkLayer sale**

Any order placed through SparkLayer that completes successfully counts as a sale. The buyer must reach the order complete page, and your eCommerce platform must register the order as a successful sale. Test orders from [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order) are marked as tests, so they don't count towards your plan.

## Check your sales for a period

1. Go to **Orders** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/activity)), or **SparkLayer Wholesale > Orders** in the Shopify app.
2. Choose a period from the first menu: **Last 7 days** (the default), **Last 30 days**, **Last 90 days** or **Custom**, which opens a date picker.
3. Choose which orders to include from the second menu: **All activity types**, **Orders** or **Awaiting merchant**.
4. Click **Orders**, **Total sales** or **Avg. order** to show that figure on the chart.

| Figure | What it shows |
| --- | --- |
| **Orders** | How many B2B orders were placed in the period. |
| **Total sales** | The total value of those orders. |
| **Avg. order** | The average value of an order in the period. |

**Reading the changes and the chart**

- Each figure shows its change from the previous period, the period of the same length just before it. A rise is green with an up arrow, and a fall is grey with a down arrow. A dash means there's nothing to compare.
- **New** means SparkLayer wasn't installed for the whole previous period, so there's nothing fair to compare with yet.
- The chart draws this period as a solid line and the previous period as a dashed line, with both date ranges in the legend. It plots one point a day for 7 and 30 days, and one a week for 90 days. Hover over the chart to see the figure for a day or week.

## Find an order in Sales history

**Sales history** lists the orders in the period and type you've chosen, newest first. It shows the latest 25. When there are more, the foot of the list says how many.

1. Go to **Orders** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/activity)), or **SparkLayer Wholesale > Orders** in the Shopify app and choose a period.
2. Find the order in **Sales history**.
3. Click its number to open the order in Shopify.

To see every B2B order in your Shopify admin, click **View in Shopify** at the top of **Sales history**. It opens **Orders** in Shopify, filtered to B2B orders.

| Column | What it shows |
| --- | --- |
| **Order** | The order number. For an order, it links to the order in Shopify. An **Awaiting merchant** number, such as P#1264, has no Shopify order yet, so it isn't a link. |
| **Date** | The date and time the order was placed, for example 14 Sept 2026, 10:42. |
| **Type** | **Order**, or **Awaiting merchant** for an order that isn't completed in Shopify yet, such as a draft order. |
| **Shipping address** | The company and the address the order ships to. |
| **Amount** | The order total. |

**Awaiting merchant** numbers start with your purchase ID prefix, which you can change in **Settings > Configurations > Store** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Store** in the Shopify app. See [Settings](https://docs.sparklayer.io/help/dashboard/settings.md#store).

## Before your first order

Until your first B2B order, **Sales history** says **No B2B orders yet**. Click **Place a test order** to go to [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order) and order as a buyer would.

If you've had orders but none in the period you chose, it says **No orders in this period**. Choose a longer period.

## FAQs

**Why isn't an order showing in Orders?**

First, check the period and type you've chosen. **Awaiting merchant** orders are hidden when you choose **Orders**.

Orders only shows orders placed through SparkLayer that completed successfully. It doesn't include retail orders placed through your store's own checkout, or orders where the buyer didn't reach the order complete page.

**Where are quotes?**

Manage quotes as described in [Work on a quote](https://docs.sparklayer.io/help/ordering/work-on-a-quote.md). A quote waiting for your reply may also be listed as **Awaiting merchant**, numbered with your purchase ID prefix.

**Why is an order a draft in Shopify?**

**Shopify only:**

Orders paid with a manual method, such as Pay by Invoice, arrive as draft orders by default. To complete them automatically, turn on **Auto-complete draft orders** in **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app. See [Managing integrations](https://docs.sparklayer.io/help/integrations/managing-integrations.md#set-shopify-order-actions).


---

# Settings

URL: https://docs.sparklayer.io/help/dashboard/settings

SparkLayer's Settings: feature switches and store details in Configurations, B2B shipping methods, API keys for your ERP, and email and invoice templates.

> **Quick summary**
>
> - **Settings** has 4 pages: **Configurations** (feature switches and store details), **Shipping** (B2B-only shipping methods), **API** (keys for your ERP or other systems) and **Templates** (your own emails and invoices). In the Shopify app they're tabs under **Settings**.
> - Start at **Settings > Configurations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations** in the Shopify app. Its cards are **Ordering**, **Quotes and invoices**, **Pricing and cart** and **Store**.
> - **Quotes** need the Pro plan or the Quoting Engine add-on (on Starter and Growth), and **Invoices** need Growth. The API needs Pro. SparkLayer shipping rates need Starter. Email and translation templates are on every plan, and invoice templates need Growth. See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
> - **Auto-complete draft orders** has moved to **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app, and the storefront widgets to **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app.

## Settings at a glance

| Page | Where | What it's for |
| --- | --- | --- |
| [Configurations](#configurations) | **Settings > Configurations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations** in the Shopify app | Switch features on or off, and set your store details, email domain and purchase IDs. |
| [Shipping](#shipping) | **Settings > Shipping** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping** in the Shopify app | Optional B2B-only shipping methods, and which method checkout pre-selects. |
| [API](#api) | **Settings > API** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/api)), or **SparkLayer Wholesale > Settings > API** in the Shopify app | Connect your ERP or another system to SparkLayer. Pro plan. |
| [Templates](#templates) | **Settings > Templates** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/theme)), or **SparkLayer Wholesale > Settings > Templates** in the Shopify app | Your own invoice layout, email notifications and translations. Needs a developer. |

**What moved from the old Settings**

| Was | Now |
| --- | --- |
| **Settings > General** | **Settings > Configurations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations** in the Shopify app, in the cards below. |
| **Apply tiered pricing across variants** | The **Tiered pricing across variants** switch, under **Pricing and cart**. |
| **Auto-complete Shopify Draft orders** | **Auto-complete draft orders** in **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app. |
| **Stock level display limit** | **Settings > Configurations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations** in the Shopify app. See [Set a stock level display limit](https://docs.sparklayer.io/help/storefront/stock-display.md#set-a-stock-level-display-limit). |
| **Frontend widgets** | **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app. See [Storefront interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md). |
| **API keys** | **Settings > API** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/api)), or **SparkLayer Wholesale > Settings > API** in the Shopify app. |
| Onboarding steps on Home | **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app. See [Get started](https://docs.sparklayer.io/help/get-started.md). |

## Configurations

**Settings > Configurations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations** in the Shopify app holds the switches for SparkLayer's features and your store-wide settings. Change the switches and fields you need, then click **Save** in the save bar that appears. Rows with **Edit** open a window that saves separately.

Need a hand? Click **Free setup assistance** at the top of the page to book a free call with our team.

A feature your plan doesn't include shows the plan it needs, such as **Pro**, and an **Unlock** button instead of a switch. Click **Unlock** to see what the feature does and start a free trial. See [Your plan](https://docs.sparklayer.io/help/dashboard/plan-and-features.md#unlock-a-feature).

### Ordering

These settings control what B2B customers can do when they order.

| Setting | What it does | Default |
| --- | --- | --- |
| **Company users** | Customers can create teams that share orders, shopping lists and addresses. See [Company users](https://docs.sparklayer.io/help/customers/company-users.md). | On |
| **Company locations** | Customers in a company choose which location they're buying for, and get that location's pricing. See [Company locations](https://docs.sparklayer.io/help/customers/company-locations.md). | On |
| **Multi-location stock** | Choose which inventory locations customers can buy stock from. Needs the Growth plan or above. See [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md). | Off |
| **Recurring orders** | Customers can set orders to repeat on a schedule. | Off |
| **Payments visibility** | Shows the payment status of orders in the My Account area. | On |

### Quotes and invoices

These settings cover quotes, invoices and the messages and emails around an order.

| Setting | What it does | Plan |
| --- | --- | --- |
| **Quotes** | Customers request quotes from their cart and you reply with prices. See [Quoting](https://docs.sparklayer.io/help/ordering/quoting.md). | Pro, or the Quoting Engine add-on on Starter and Growth |
| **Quote statuses** | The statuses you use to manage quotes. Shown only while **Quotes** is on. | Pro, or the Quoting Engine add-on on Starter and Growth |
| **Invoices** | Send invoices to your B2B customers directly from SparkLayer. See [Invoices](https://docs.sparklayer.io/help/ordering/invoices.md). | Growth |
| **Timeline and communications** | Customers and sales agents can send messages on quotes and orders. See [Timeline](https://docs.sparklayer.io/help/customers/timeline.md). | Every plan |
| **Purchase notifications** | Who gets an email when a quote or order updates and nobody is assigned to it. | Every plan |

#### Set up quote statuses

1. In **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app, turn on **Quotes** and save.
2. Click **Edit** next to **Quote statuses**.
3. Enter a **New status**, for example "Awaiting approval", and click **Add status**. To remove a status, click **Remove** next to it.
4. Click **Done**.

New quotes start in the status marked **Default**, which is **Quote Requested** unless you change it.

#### Choose who gets purchase notifications

1. Click **Edit** next to **Purchase notifications**.
2. Enter one or more **Email addresses**, separated by commas.
3. Click **Save**.

Until you add an address, it says "No one is emailed when quotes and orders update."

### Pricing and cart

These settings control how prices are worked out and shown, and how the SparkLayer cart behaves.

| Setting | What it does | Default |
| --- | --- | --- |
| **Tax-inclusive prices** | Lets price lists show prices including tax, using a `display_tax_rate` column in the pricing CSV. It changes what buyers see, not what they pay. See [How prices are shown](https://docs.sparklayer.io/help/pricing/pricing-display.md). | Off |
| **Tiered pricing across variants** | Quantity tiers count every variant of a product together. For example, 6 small and 6 large count as 12 towards a 12+ tier. | On |
| **Hide AI features in the cart** | Hides the [Intelligent Cart](https://docs.sparklayer.io/help/ordering/intelligent-cart.md) AI features in the SparkLayer cart. | Off |
| **Cart search type** | How search works in the SparkLayer cart. | **Search** |

**Tiered pricing across variants** and **Hide AI features in the cart** also appear in **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app, marked **Also in Configurations**. They're the same settings, so change them in either place.

### Store

These settings hold your store's details, the domain SparkLayer emails come from and the format of purchase IDs.

| Setting | What it's for |
| --- | --- |
| **Store details** | The store name, address, phone number, email and website that B2B customers see, for example in emails. |
| **Custom email domain** | Send SparkLayer's emails from your own domain instead of `no-reply@mail.sparklayer.io`. Needs the Pro plan or above. |
| **Purchase ID prefix** and **Purchase ID postfix** | Added to the IDs of purchases that exist only in SparkLayer, such as quotes and orders awaiting approval. The default prefix is **P#**, so an ID looks like P#1264. |

#### Change your store details

SparkLayer syncs your store details from Shopify. To override what B2B customers see, change them here.

1. In **Settings > Configurations > Store** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Store** in the Shopify app, click **Edit** next to **Store details**.
2. Change the **Store name**, **Store address**, **Phone number**, **Email** or **Website URL**.
3. Click **Save**.

Your changes don't sync back to Shopify. 

#### Send emails from your own domain

Sending emails from your own domain needs the Pro plan or above.

1. Click **Edit** next to **Custom email domain**.
2. Tick **Use my own domain for SparkLayer emails**.
3. Enter the **Email user** (the part before the @) and your **Domain**, then click **Save**.

Emails to and from customers then use your domain. Our team helps you verify it.

## Shipping

By default, SparkLayer uses your store's own shipping rates, and B2B customers see them at checkout. To charge B2B customers differently, create your own shipping methods, priced by customer group, order total or weight. You turn them on with **Use SparkLayer shipping rates** at **Settings > Shipping** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping** in the Shopify app. SparkLayer shipping rates need the Starter plan or above.

| On the page | What it's for |
| --- | --- |
| **Shipping rates** | Switch between your store's rates and SparkLayer shipping rates. On Shopify, **Shopify shipping settings** opens your Shopify rates. |
| **Shipping methods** | The B2B-only methods customers choose at checkout, each with bands that set its cost. |
| **Automatic shipping selection** | On Shopify, which method checkout pre-selects. |

For the steps, see [Shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md): [Turn on SparkLayer shipping rates](https://docs.sparklayer.io/help/ordering/shipping-rules.md#turn-on-sparklayer-shipping-rates), [Create a shipping method](https://docs.sparklayer.io/help/ordering/shipping-rules.md#create-a-shipping-method), [Add shipping bands](https://docs.sparklayer.io/help/ordering/shipping-rules.md#add-shipping-bands) and [Choose which method is pre-selected](https://docs.sparklayer.io/help/ordering/shipping-rules.md#automatic-shipping-selection).

## API

The [SparkLayer API](https://docs.sparklayer.io/developers/api.md) lets another system, such as an ERP, send SparkLayer your prices, customers and stock. It's on the Pro and Enterprise plans. Below Pro, **Settings > API** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/api)), or **SparkLayer Wholesale > Settings > API** in the Shopify app says **The SparkLayer API is on Pro**, with **Compare plans** and **Read the API docs**.

Connecting a system is a job for your developer or integration partner. Pro includes a guided integration call.

### Connect your ERP

Until you've connected a system, **Settings > API** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/api)), or **SparkLayer Wholesale > Settings > API** in the Shopify app starts with **Connect your ERP**:

1. Choose **Your ERP** (NetSuite, Sage, Microsoft Dynamics 365, Xero or QuickBooks, or Something else) and what to **Sync first**: **Prices**, **Customers and companies** or **Stock**. Most stores start with prices.
2. **Give your developer access.** Click **Create test key** for a key that only works on your test store, and **Invite developer** to invite them to your account.
3. **Send them the brief.** Click **Copy brief** and send it to your developer. It's written from your store's real setup: price list handles, group tags, and how SKUs and customers match.
4. **Check what's arriving.** Once your developer starts sending data, click **Run check**. SparkLayer checks each push against your catalogue and customers, so problems show up here, not with buyers.

Stuck, or no developer? Click **Book integration call**.

Once your ERP is connected, the card shows when it last synced. To add another, click **Connect another system**.

### Create an API key

1. Go to **Settings > API** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/api)), or **SparkLayer Wholesale > Settings > API** in the Shopify app and click **Create API key**.
2. Enter a **Key name**, such as "NetSuite ERP", so you can tell your keys apart, and click **Create key**.
3. Copy the **Client ID** and **Client secret** with their **Copy** buttons, then click **Done**. Your developer uses both to connect to the [SparkLayer API](https://docs.sparklayer.io/developers/api.md).

> **Copy the client secret straight away**
>
> The client secret is only shown once, when you create the key. Store it somewhere safe before you click **Done**.

**API keys** lists each key's **Name**, **Client ID**, when it was **Created** and when it was **Last used**.

To stop a key working, click **Revoke** next to it, then **Revoke key**. Anything using it stops working straight away, and you can't undo this.

## Templates

Templates change specific content your B2B buyers see. They're an advanced feature that needs a developer, because editing one means working with code (Liquid, HTML and CSS). If you'd like help, book a call with our team.

Email and translation templates are on every plan. Invoice templates need the Growth plan or above.

| Template covers | What you can change |
| --- | --- |
| **Invoices** | Your own layout and wording on the [invoice](https://docs.sparklayer.io/help/ordering/invoices.md) PDF customers download. |
| **Email notifications** | Order, quote and account emails, such as the order review emails sent with [company users](https://docs.sparklayer.io/help/customers/company-users.md) and [quote](https://docs.sparklayer.io/help/ordering/quoting.md) notifications. |
| **Translations** | Language packs beyond the built-in ones. |

Templates only change SparkLayer's emails, PDFs and text, not your website's theme. For the full detail, see [Templates](https://docs.sparklayer.io/developers/templates.md) in the developer docs.

### Create a template

1. Go to **Settings > Templates** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/theme)), or **SparkLayer Wholesale > Settings > Templates** in the Shopify app.
2. Click **Create template**. SparkLayer creates a template theme for you to edit.

A new template is empty, so it falls back to SparkLayer's core templates and language files until you add files to it. For the developer guide, click **How templates work**. 

**Files, revisions and the templating language**

**Add files only when you'll change them.** Once added, a file isn't updated from SparkLayer's core templates. If a new feature adds a section to a core template, your copy won't get it. Copy the change into your file, or create a new template.

| File type | What it's for |
| --- | --- |
| **Language** | A language file for the templates. If it matches your store's language, SparkLayer's core templates use it even if you haven't created any templates, falling back to SparkLayer's language files for any missing key. The SparkLayer `en` language file is the last resort. |
| **Sections** | Used in emails only: a reusable header and footer for your email templates. |
| **Emails** | The emails sent by SparkLayer. |
| **PDF** | The PDFs created by SparkLayer. |

**Templating language.** Templates are [written in Liquid](https://shopify.github.io/liquid/). They must be valid HTML, with the CSS written in the template. All CSS is inlined when the template is rendered, for the best compatibility with email clients. SparkLayer only supports modern email clients from the last few years. Language files are written in JSON.

**Revisions.** Edit a file in the SparkLayer editor and click **Save** to create a revision. To go back, open a previous revision from the **Revisions** drop-down and save it. For bigger changes, download a ZIP file of the template so a developer can work on it with their own tools. Then zip it up and upload it. Only the known template files are processed, so extra files, such as images, aren't added.


---

# Test mode

URL: https://docs.sparklayer.io/help/dashboard/test-mode

Use test mode to switch the SparkLayer Dashboard between your live store and a test store, so you can try out pricing and customer changes safely.

> **Quick summary**
>
> - Test mode gives one SparkLayer account 2 environments: your live store (production) and a test store (staging).
> - Switch between them with the **Test mode** switch in the Dashboard menu. Each environment has its own data, so what you do in one doesn't affect the other.
> - It's on the Pro and Enterprise plans. Setting it up is optional, and you can add or change your test store at any time.

## How it works

Test mode switches the data you see in the [SparkLayer Dashboard](https://docs.sparklayer.io/help/dashboard.md) between the 2 stores you connect. Turn the switch on, and every section reloads with your test store's data. Anything you change then applies only to the test store. Turn it off to go back to your live store.

Use it when:

- You want a test account on your live store, to test pricing and customer data
- You want to set up SparkLayer on a development (sandbox) store before going live

You don't need test mode to launch. You can test on your live store with a test B2B customer.

**Shopify only:**

On Shopify, [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order) creates one for you and places a test order that doesn't count towards your plan.

## Before you start

- **The Pro or Enterprise plan.** See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
- **A second store to test on**, such as a development or sandbox store on your platform.

## Connect your live and test stores

You connect both stores at **Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app, which you first see when you create your SparkLayer account. Connect your live store first, then add your test store. The steps below use Shopify as the example. 

### Connect your live store

1. Check the **Test mode** switch in the Dashboard menu is **off**. 
2. 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.
3. Under **Your platform**, choose your platform, for example **Shopify** ("All versions, including Shopify Plus.").
4. In **Shopify store**, enter your live store's address: the part before `.myshopify.com`, for example `my-live-store`.
5. Shopify opens and asks you to authorise the SparkLayer app. Approve it to finish connecting. 

### Add your test store

1. Turn the **Test mode** switch **on**. Its label reads "Load data from test environment".
2. 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.
3. Choose your platform and enter your test store's address in **Shopify store** (for example `my-test-store`), if it isn't already filled in.
4. Authorise the SparkLayer app in Shopify. You can skip the billing step for a test store.
5. Work through the steps on **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app for your test store, as you did for your live store. See [Get started](https://docs.sparklayer.io/help/get-started.md).

## Switch between live and test

Turn the **Test mode** switch on to work with your test store, and off to work with your live store. The Dashboard reloads each section with that store's data.

## Add test mode to an existing Shopify installation

**Shopify only:**

If SparkLayer is already installed on your live Shopify store, [contact our support team](https://docs.sparklayer.io/help/support.md) to add a test store. Our team sets it up with you, so you keep your live setup.

Don't uninstall SparkLayer to do this yourself. Uninstalling ends your subscription and deletes your SparkLayer data: see [What happens to your data when you uninstall](https://docs.sparklayer.io/help/dashboard/billing.md#data-on-uninstall).

## Next steps

- [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md): Test as a B2B customer, invite your first customers and go live
- [Get started](https://docs.sparklayer.io/help/get-started.md): The 5 Setup steps, which you repeat for your test store


---

# Your plan and usage

URL: https://docs.sparklayer.io/help/dashboard/plan-and-features

Check your SparkLayer plan and this month's usage, start a 14-day free trial, unlock a paid feature, and browse everything SparkLayer does in Explore features.

> **Quick summary**
>
> - Your plan shows in the plan card at the foot of the SparkLayer Dashboard's sidebar, or under **Plan** in the Shopify app: **Plan card** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Plan** in the Shopify app. Home has a plan card too.
> - Every paid plan (Starter, Growth and Pro) has a 14-day free trial, with no card needed. On Shopify you're billed through Shopify; on other platforms, see [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md).
> - Going over your monthly B2B order allowance doesn't stop anything working. Your plan card tells you, and suggests a plan that fits.
> - **Explore features** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Explore features** in the Shopify app lists what SparkLayer does, the plan each feature needs and a way to set it up or preview it. For the full comparison, see [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).

## Your plan

Your plan sets how many B2B orders you can take a month, how many price lists and sales agents you can have, and which features you get. SparkLayer shows how much you've used this month, so you can see when it's time to change.

| Where | What you see |
| --- | --- |
| **SparkLayer Dashboard**: the plan card at the foot of the sidebar | Your plan, a status badge, meters for **B2B orders this month**, **Price lists** and **Sales agents**, and a button such as **Compare plans**. |
| **Shopify app**: **Plan** in the menu | Opens the plans window. |
| **Home**, in both versions | A plan card with the same meters under **Your usage this month**, and what your plan gives you or what the next one adds. |

### What the badge means

| Badge | What it means |
| --- | --- |
| **Free** | You're on the free Basic plan, with room to spare. |
| **Nearly full** | You've used 80% or more of this month's B2B orders, or on Basic, of your 3 price lists. |
| **At limit** | On Basic, you've used all of this month's B2B orders or all 3 price lists. |
| **Over limit** | On any plan, you've taken more B2B orders this month than your plan includes. |
| **Trial · 5 days left** (for example) | You're on a free trial, with the days left. |
| **Active** | You're on a paid plan. |

**What counts as a B2B order**

Only orders placed through SparkLayer count towards your allowance. Retail orders through the same store don't count, and test orders from [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order) are marked as tests, so they don't count either. The count starts again each month.

### If you go over your allowance

Nothing is blocked. Your buyers keep ordering and SparkLayer keeps working. The plan card changes to **Nearly full**, then **Over limit**, and suggests the plan that fits your order pace. Our team may also get in touch to talk about whether another plan would suit you better.

## Change your plan

1. Open the plans window: click the button on your plan card, such as **Compare plans**, or **Plan** in the Shopify app's menu.
2. Choose **Starter**, **Growth** or **Pro**. Each shows its monthly price, B2B orders a month and sales agents. The plan that fits your last 7 days of orders is marked **Recommended**.
3. Click **Start free trial**. On Pro, the button is **Change plan**.
4. On Shopify, confirm the change in your Shopify admin. Shopify then bills you monthly. On other platforms, see [How you're billed](https://docs.sparklayer.io/help/dashboard/billing.md#how-youre-billed).

To move to a cheaper plan, to the free Basic plan or to cancel, see [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md).

Need more than 150 orders a month? Click **Talk to us about Enterprise** in the plans window. On Enterprise, see your plan and its cost under **Plan** in the account menu: click your name at the foot of the Dashboard's sidebar.

**Plans at a glance**

| Plan | Price | B2B orders a month | Price lists | Sales agents |
| --- | --- | --- | --- | --- |
| Basic | Free | 5 | 3 | 0 |
| Starter | $49 a month | 50 | Unlimited | 1 |
| Growth | $149 a month | 100 | Unlimited | 2 |
| Pro | $299 a month | 150 | Unlimited | 5 |

For what each plan includes, see [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md). The [SparkLayer pricing page](https://www.sparklayer.io/pricing/) always has the latest prices.

## Free trials

Every paid plan comes with a 14-day free trial. You don't need a card, and you can cancel any time.

- Starting a trial switches on that plan's features straight away.
- During the trial, the plan card counts down the days left, and features from the plan are marked **On your trial**.
- You don't need to do anything to stay on the plan. When the trial ends, you're billed for the plan you chose, and your reps, invoices and price lists stay exactly as they are. The plan card's **Keep Growth** button (or your trial's plan) confirms you're staying. 

To avoid being billed, change plan or cancel before the trial ends: see [Cancel before the trial ends](https://docs.sparklayer.io/help/dashboard/billing.md#cancel-before-the-trial-ends).

## Unlock a feature

A feature your plan doesn't include shows the plan it needs, such as **Growth** or **Pro**. To see what it does before you upgrade, click it or click **Unlock**:

1. Click the locked feature: for example **Unlock** next to **Quotes** in **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app, or **Sales agents** on the Basic plan.
2. Read what it does, the plan it's **Included in** and that plan's price, orders and sales agents.
3. Click **Try Growth free for 14 days** (or the plan it needs) to open the plans window, then follow [Change your plan](#change-your-plan).

Everything you set up on your current plan stays when you upgrade. If the feature is already in your plan, clicking it takes you straight to its screen.

| Feature | Plan it needs |
| --- | --- |
| [Sales agents](https://docs.sparklayer.io/help/sales-reps.md) | Starter |
| [SparkLayer shipping rates](https://docs.sparklayer.io/help/ordering/shipping-rules.md) | Starter |
| [SparkLayer Invoices](https://docs.sparklayer.io/help/ordering/invoices.md) (automatic PDF invoices, payment reminders and your own invoice template) | Growth |
| [Advanced discounts](https://docs.sparklayer.io/help/pricing/discounts.md) | Growth |
| [Quotes](https://docs.sparklayer.io/help/ordering/quoting.md) | Pro, or the Quoting Engine add-on on Starter and Growth ($49 per month). Not on Basic. |
| [Xero](https://docs.sparklayer.io/help/integrations/accountancy/xero.md) and [QuickBooks](https://docs.sparklayer.io/help/integrations/accountancy/quickbooks.md) | Pro |
| [The SparkLayer API](https://docs.sparklayer.io/help/dashboard/settings.md#api) | Pro |
| More than 3 [price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md) | Starter |

[Net terms and credit limits](https://docs.sparklayer.io/help/guides/net-terms.md) (Pay on Account and Pay by Invoice), email and translation templates, forms, companies and company users aren't locked on any plan. For every feature by plan, see [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).

## Explore features

**Explore features** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Explore features** in the Shopify app is a catalogue of what SparkLayer does, with the plan each feature needs and a way to set it up.

1. Go to **Explore features** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Explore features** in the Shopify app.
2. Choose a category: **Basics**, **Advanced** or **Extras**.
3. Click a feature to see examples, then use its buttons to set it up, preview it or **Read the docs**.

| Category | What's in it |
| --- | --- |
| **Basics** | The essentials, on every plan: B2B storefront widgets, price lists, assigned pricing, order rules, stock display and payment methods. |
| **Advanced** | How customers buy, pay and are managed as you grow: B2B catalogs, forms, sales agent ordering (Starter), net terms and credit allocations (every plan) and advanced discounts (Growth). |
| **Extras** | The wider operations around B2B: B2B shipping (Starter), invoicing (Growth), Xero and QuickBooks (Pro), quoting (Pro, or an add-on on Starter and Growth) and company users. |

A feature your plan doesn't include shows its plan as a badge, and says it's free for 14 days. To [unlock it](#unlock-a-feature), click its button.

### Hide a suggestion

To clear a feature you don't need from the list, open it and click **Hide suggestion**. To bring hidden features back, click **Show hidden** under the list.


---

# Billing, trials and cancelling

URL: https://docs.sparklayer.io/help/dashboard/billing

How SparkLayer bills you on each platform, what happens when your free trial ends, and how to upgrade, downgrade or cancel, and what uninstalling deletes.

> **Quick summary**
>
> - How you're billed depends on your platform: through Shopify on Shopify, through Wix on Wix, and by arrangement with our team on BigCommerce, WooCommerce and Magento. Plans are priced in US dollars.
> - Every paid plan starts with a 14-day free trial. When it ends, you're billed for the plan you chose, unless you change plan or cancel first.
> - Change plan at any time in the plans window: **Plan card** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Plan** in the Shopify app. On Shopify, you can move down to the free **Basic** plan without uninstalling.
> - Uninstalling SparkLayer ends your subscription. Treat it as deleting your SparkLayer data: export what you need and [contact us](https://docs.sparklayer.io/help/support.md) first.

## How you're billed on each platform

| Platform | How billing works |
| --- | --- |
| **Shopify** | Through Shopify. You approve the charge in your Shopify admin, and SparkLayer appears on your Shopify bill at **Settings > Billing** ([open in the Shopify admin](https://admin.shopify.com/settings/billing)). Shopify's billing rules apply, so refunds go through Shopify too: see [Refund policy](https://docs.sparklayer.io/help/policies/refund-policy.md). |
| **Wix** | Through your Wix account, monthly or annually. You confirm the plan in Wix when you install. See [Wix FAQs](https://docs.sparklayer.io/help/platforms/wix/faqs.md#how-does-billing-work). |
| **BigCommerce** | Our team contacts you to agree the most suitable plan, billed monthly or annually. See [BigCommerce FAQs](https://docs.sparklayer.io/help/platforms/bigcommerce/faqs.md#how-does-billing-work). |
| **WooCommerce** | Managed in the SparkLayer Dashboard, from the plan card at the foot of the sidebar. See [WooCommerce FAQs](https://docs.sparklayer.io/help/platforms/woocommerce/faqs.md#how-does-billing-work). |
| **Magento** | Managed in the SparkLayer Dashboard. Magento needs the Enterprise plan, which you agree with our team. See [Magento FAQs](https://docs.sparklayer.io/help/platforms/magento/faqs.md#how-does-billing-work). |

The free **Basic** plan is only on Shopify. On other platforms, you start with a free trial of a paid plan. For what each plan includes, see [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).

### Monthly or annual

Plans are billed monthly by default. Annual billing is available on some platforms, such as Wix and BigCommerce. To ask about paying annually, [contact us](https://docs.sparklayer.io/help/support.md). 

## Free trials

Every paid plan (Starter, Growth and Pro) comes with a 14-day free trial, and you don't need to add a card. Starting a trial switches on that plan's features straight away, and the plan card counts down the days left. See [Free trials](https://docs.sparklayer.io/help/dashboard/plan-and-features.md#free-trials).

### When the trial ends

You're billed for the plan you chose when you started the trial. You don't need to do anything to stay on it, and everything you set up during the trial stays as it is.

### Cancel before the trial ends

To avoid being billed, change plan or cancel before the 14 days are up:

- **On Shopify**, move to the free [Basic plan](#downgrade) to keep SparkLayer and your setup, or [uninstall SparkLayer](#cancel) to stop using it.
- **On other platforms**, [contact us](https://docs.sparklayer.io/help/support.md) or [uninstall SparkLayer](#cancel).

Forgot to cancel? You can ask for 50% off your first billing cycle within 5 days (monthly) or 7 days (annual): see [Refund policy](https://docs.sparklayer.io/help/policies/refund-policy.md#eligibility). Need more time to decide? [Contact our team](https://docs.sparklayer.io/help/support.md) to ask about extending your trial.

## Upgrade

1. Open the plans window: click the button on your plan card, such as **Compare plans**, or **Plan** in the Shopify app's menu.
2. Choose the plan and click **Start free trial** (or **Change plan**).
3. On Shopify, confirm the change in your Shopify admin.

Everything you've set up stays when you upgrade. See [Change your plan](https://docs.sparklayer.io/help/dashboard/plan-and-features.md#change-your-plan). For Enterprise, click **Talk to us about Enterprise** in the plans window.

## Downgrade

To move to a cheaper plan, choose it in the plans window, as in [Upgrade](#upgrade). On BigCommerce, ask [our team](https://docs.sparklayer.io/help/support.md) to move you down a plan.

On Shopify, you can move to the free **Basic** plan without uninstalling, so you keep your account and your setup. 

When you move down a plan, you lose the features the lower plan doesn't include. For example, on Basic:

- **Price lists:** Basic includes 3. 
- **Sales agents:** Basic has none, so [sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md) and [quotes](https://docs.sparklayer.io/help/ordering/quoting.md), which need a sales agent to review them, aren't available. 
- **B2B orders:** Basic includes 5 a month. Going over doesn't block orders: see [If you go over your allowance](https://docs.sparklayer.io/help/dashboard/plan-and-features.md#if-you-go-over-your-allowance).
- **Settings for paid features**, such as SparkLayer shipping rates, may stay as they are but become locked. See [If you set up shipping during a trial](https://docs.sparklayer.io/help/ordering/shipping-rules.md#if-you-set-up-shipping-during-a-trial).

Check what each plan includes in [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md) before you change.

## Cancel

To cancel your subscription, uninstall SparkLayer from your store. Billing stops straight away. Your platform's guide has the steps: [Shopify](https://docs.sparklayer.io/help/platforms/shopify/uninstall.md), [BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce/uninstall.md), [Wix](https://docs.sparklayer.io/help/platforms/wix/uninstall.md), [WooCommerce](https://docs.sparklayer.io/help/platforms/woocommerce/uninstall.md) or [Magento](https://docs.sparklayer.io/help/platforms/magento/uninstall.md).

Depending on when your billing cycle started, you may still see a charge after uninstalling. [Contact us](https://docs.sparklayer.io/help/support.md) and we'll look into it. Refunds are only for significant technical problems: see [Refund policy](https://docs.sparklayer.io/help/policies/refund-policy.md).

On Shopify, if you want to stop paying but might come back, move to the free [Basic plan](#downgrade) instead.

## What happens to your data when you uninstall

Treat uninstalling as deleting your SparkLayer data. Uninstalling ends your subscription and disconnects SparkLayer from your store, and your SparkLayer account is then deleted. While it's scheduled for deletion, a warning shows at the top of the SparkLayer Dashboard. 

Before you uninstall:

- **Keep the data you need**, such as your price lists, customer groups and settings. For example, 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, open the **⋯** menu next to each price list and click **Download CSV**.
- **Contact us first if you plan to reinstall, move to another store or need a test store.** We can help without you losing your setup. See [Contact support](https://docs.sparklayer.io/help/support.md).
- **Ask for a refund before you uninstall**, if you're asking for one. We can only look into a problem while SparkLayer is installed: see [Refund policy](https://docs.sparklayer.io/help/policies/refund-policy.md#how-to-request-a-refund).
- **Plan to remove the widget code** from your theme. Uninstalling doesn't remove it for you.

You don't need to uninstall to try something out. For a test store, see [Test mode](https://docs.sparklayer.io/help/dashboard/test-mode.md).

## Several stores or teams

Each store you run SparkLayer on has its own SparkLayer account (a team), with its own plan and subscription. To add a store, [create a new team](https://docs.sparklayer.io/help/dashboard/account.md#create-a-new-team) and connect it. Every team is linked to your login, so you sign in once to reach them all. 

On a development or test store, our team can turn on a developer mode so you can use SparkLayer before you choose a plan. See [Shopify FAQs](https://docs.sparklayer.io/help/platforms/shopify/faqs.md) or [contact us](https://docs.sparklayer.io/help/support.md).

## FAQs

**Do I need a card to start a free trial?**

No. On Shopify and Wix, you approve the plan in your store's admin, and you're billed through your platform once the trial ends.

**Why was I charged after I uninstalled?**

Depending on when your billing cycle started, a charge for the current cycle may still come through. On Shopify, charges and refunds go through Shopify's billing system. [Contact us](https://docs.sparklayer.io/help/support.md) and we'll look into it. See [Refund policy](https://docs.sparklayer.io/help/policies/refund-policy.md#processing-and-shopify-billing).

**What happens if I go over my plan's B2B orders?**

Nothing is blocked. Your plan card shows **Over limit** and suggests a plan that fits. See [If you go over your allowance](https://docs.sparklayer.io/help/dashboard/plan-and-features.md#if-you-go-over-your-allowance).


---

# Your account and team

URL: https://docs.sparklayer.io/help/dashboard/account

Manage your SparkLayer account: find your Site ID, change your password, invite team members, set up a team for another store and change the team owner.

> **Quick summary**
>
> - Click your name at the foot of the SparkLayer Dashboard's sidebar to open the account menu: **Account** (your details, including your **Site ID**), **Password**, **Plan** and **Team**.
> - Your plan and usage are on the plan card, not here. See [Your plan and usage](https://docs.sparklayer.io/help/dashboard/plan-and-features.md).
> - Your company details can't be edited in the Dashboard. To change them, use our [change request form](https://forms.clickup.com/f/4b3cj-134/QGWV5GH8KV7KHQEBUS).
> - Each store you run SparkLayer on has its own team, with its own plan. Uninstalling SparkLayer from your store ends your subscription and deletes your SparkLayer account: see [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md#data-on-uninstall).

## Edit your account details

Click your name at the foot of the Dashboard's sidebar, then **Account**.

| Field | What it is |
| --- | --- |
| **Name** | Your full name. |
| **Email address** | The email address you sign in to the SparkLayer Dashboard with. |
| **Company Name** | The company name registered with SparkLayer. |
| **Website** | The website address registered with SparkLayer. |
| **Site ID** | Your site's unique identifier, used when you set up the [storefront interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) and the [SparkLayer API](https://docs.sparklayer.io/developers/api.md). |

To change your company information, use our [change request form](https://forms.clickup.com/f/4b3cj-134/QGWV5GH8KV7KHQEBUS). You can't edit it yourself, because SparkLayer relies on it to work, and changes could cause errors in your integration.

## Check or change your plan

Your plan is on the plan card at the foot of the SparkLayer Dashboard's sidebar, or under **Plan** in the Shopify app: **Plan card** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Plan** in the Shopify app. On Shopify, all billing goes through Shopify, so you confirm any plan change in your Shopify admin. See [Your plan and usage](https://docs.sparklayer.io/help/dashboard/plan-and-features.md), and for billing on other platforms, downgrading and cancelling, [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md).

## Change your password

To change the password you sign in to the Dashboard with, click your name at the foot of the Dashboard's sidebar, then **Password**. If you've forgotten it, reset it from the [SparkLayer login page](https://app.sparklayer.io/forgotten-password).

## Invite team members

Team members get full access to your SparkLayer account and can make changes. Only the team owner can invite them.

1. In the SparkLayer Dashboard, click your name at the foot of the sidebar, then **Team**, and click **Add team member**.
2. In **Add team members**, enter the person's **Email Address** and send the invitation. 
3. They receive an email inviting them to join your team. To get started, they click **Accept Invitation** and create an account.

To give a developer access for an API integration, see [Connect your ERP](https://docs.sparklayer.io/help/dashboard/settings.md#connect-your-erp).

## Create a new team

A team is a separate SparkLayer account for one store. Create a new team when:

- You want to trial SparkLayer on a development (test) store to try its features
- You run several stores under your brand and need a SparkLayer account for each

Every team you create is linked to your main SparkLayer login, so you sign in once to reach all of them. Each team has its own plan: see [Several stores or teams](https://docs.sparklayer.io/help/dashboard/billing.md#several-stores).

1. In the [SparkLayer Dashboard](https://app.sparklayer.io/), click the account and store switcher at the top of the sidebar.
2. Click **Create New Team**. 
3. Enter a **Company Name** (shown when you access the team) and a **Company Website** (the store the team is for).
4. Click **Create Team**.

To switch between teams, use the same switcher at the top of the sidebar. A new team starts from the beginning of setup: see [Get started](https://docs.sparklayer.io/help/get-started.md). You can then [invite team members](#invite-team-members) to it.

## Change the team owner

If you're the team owner, you can hand ownership to someone who's already a team member.

1. Click your name at the foot of the Dashboard's sidebar, then **Team**.
2. Find the team member and click **Change owner** (the arrows icon next to their name).
3. Confirm the change.

## Delete your account

You can't delete your SparkLayer account from the Dashboard. Instead, an account becomes inactive when you uninstall or disconnect SparkLayer from your online store, and it's then deleted automatically, with its data. While an account is scheduled for deletion, a warning shows at the top of the Dashboard. 

Treat uninstalling as deleting your SparkLayer data. Before you do, keep anything you need, such as your price lists, and contact us if you plan to reinstall or move to another store. See [What happens to your data when you uninstall](https://docs.sparklayer.io/help/dashboard/billing.md#data-on-uninstall).

If you have several SparkLayer accounts, you may see this warning on any account without an active store. Check you're signed in to the right one: use the account and store switcher at the top of the sidebar to choose the store.

For anything else about deleting your account, [contact us](https://docs.sparklayer.io/help/support.md).

## Access the Dashboard from your Shopify admin

**Shopify only:**

On Shopify, you can manage SparkLayer in the Shopify app, **SparkLayer Wholesale** under **Sales channels** in your Shopify admin. See [Find your way around SparkLayer](https://docs.sparklayer.io/help/dashboard.md#two-versions).

When you open the SparkLayer Dashboard from your Shopify admin, it signs you in automatically to the Dashboard account of the team owner linked to your Shopify app installation. For security, you get restricted access if the email you sign in to Shopify with is different from the team owner's. You can't:

- Switch to other teams
- Manage teams
- Manage account details

For full access, sign out and sign back in with the team owner's details.


---

# Features we turn on for you

URL: https://docs.sparklayer.io/help/dashboard/features-on-request

See which SparkLayer features our team turns on or sets up for you, what each one does, what to tell us, and how to ask from the Dashboard or Help Center.

> **Quick summary**
>
> - Some features have no switch in the SparkLayer Dashboard: our team turns them on, or sets them up on your theme, for you. They're listed in the table below.
> - To ask, click the message icon in the [SparkLayer Dashboard](https://app.sparklayer.io/) or at the bottom right of this page. See [Contact support](https://docs.sparklayer.io/help/support.md).
> - Tell us which feature you want, which store it's for and, for theme changes, which theme. We work on a duplicate of your theme first.

## Features on request

| Feature | What it does | What to tell us | Guide |
| --- | --- | --- | --- |
| **Line-item tax** | Works out tax for each line, instead of on the cart subtotal, when your products have different tax rates. | That your products have different tax rates. | [Charge different tax rates on different products](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md#charge-different-tax-rates-on-different-products) |
| **Product data translations** (Shopify) | Shows product names and options in the customer's language, from your Shopify translations. | Your store's languages. Publish your translations in Shopify first. | [Show translated product data](https://docs.sparklayer.io/help/storefront/languages-and-international.md#show-translated-product-data-shopify) |
| **Quick Buy layout for a collection** | Shows a collection as a compact list, so buyers can build orders quickly. | Which collections, and which theme. | [Turn on quick buy mode](https://docs.sparklayer.io/help/storefront/product-display.md#turn-on-quick-buy-mode) |
| **B2B-only navigation menu** | Shows signed-in B2B customers a different menu from retail visitors. With the handle `b2b-menu`, it also sets the collections in [Catalog and Quick Order](https://docs.sparklayer.io/help/platforms/shopify/catalog-collections.md). | The menu to show, and which theme. | [Show a B2B-only navigation menu](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-only-content.md#show-a-b2b-only-navigation-menu) |
| **Compatibility settings for shipping apps** | Settings that let some shipping apps work with SparkLayer's checkout. | The shipping app you use. | [Shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md) |
| **Remove customers in bulk** | Removes customers you no longer want in SparkLayer. Removing the `b2b` tag doesn't do this. | The customers' email addresses. | [Remove a customer from B2B](https://docs.sparklayer.io/help/customers/managing-customers.md#remove-a-customer-from-b2b) |

## Ask us to turn on a feature

1. Contact our team: click the message icon (a purple speech bubble) in the [SparkLayer Dashboard](https://app.sparklayer.io/) or at the bottom right of any Help Center page, or email [support@sparklayer.io](mailto:support@sparklayer.io).
2. Say which feature you want, from the table above.
3. Say which store it's for, such as your store's web address.
4. For a change to your theme, say which theme. We make the change on a duplicate of that theme first.

> **We may ask for collaborator access**
>
> Some features are set up in your store or your theme, so our team may ask for collaborator access to make the change and check it works. On Shopify, we may also need the **Apps and channels** permission to check the SparkLayer Wholesale app's setup.

See [Contact support](https://docs.sparklayer.io/help/support.md) for when we're available and what our support covers.


---

# Pulse

URL: https://docs.sparklayer.io/help/pulse

Pulse is your sales rep workspace in the storefront: who to contact today, your tasks, quotes, carts, unpaid invoices and how each account is trading.

> **Pulse is in early access.** Request it for your sales team. [Request early access](https://feedback.sparklayer.io/get-started?choice=now). [Try the interactive demo](https://www.sparklayer.io/pulse/).

> **Quick summary**
>
> - **Pulse** is where you run your accounts from one screen: who to contact today and why, the follow-ups you've promised, quotes to chase, carts to finish, unpaid invoices and how each account is trading.
> - Open it from the **Dashboard** tab in the SparkLayer widget on your store, signed in with your sales agent account.
> - Every **Order** button in Pulse takes you straight into an order for that customer, at their prices. See [Sales rep ordering](https://docs.sparklayer.io/help/sales-ordering.md).
> - Pulse is on every paid plan, for anyone with a sales agent seat, and is in early access: request it from the callout at the top of this page. Your store owner or admin sets up your sales agent account at **Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app: see [Sales rep setup](https://docs.sparklayer.io/help/sales-reps.md) and [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md). Figures cover orders placed through your storefront only.

## What Pulse does for you

You look after a set of accounts, sometimes called your book. Pulse reads those accounts' orders, quotes, carts, invoices and trade applications, and turns them into a list of things to do: who's due to reorder, who has gone quiet, which customers are waiting on a reply, which quotes are going stale and which invoices are overdue.

Every row opens the record behind it. Every **Order** button takes you into the storefront, signed in as that customer.

Pulse doesn't change your store's SparkLayer settings. Customers, pricing and sales agents are still managed in the SparkLayer Dashboard or the SparkLayer Wholesale app in Shopify.

| To | Go to |
| --- | --- |
| See how the month is going and who needs you today | [Overview](https://docs.sparklayer.io/help/pulse/overview.md) |
| Plan who to call or visit, reply to customers and keep your follow-ups | [Task List](https://docs.sparklayer.io/help/pulse/task-list.md) |
| Follow up a cart a customer hasn't finished | [Carts](https://docs.sparklayer.io/help/pulse/carts.md) |
| Chase a quote before it goes stale | [Quotes](https://docs.sparklayer.io/help/pulse/quotes.md) |
| Check who owes money before you call | [Receivables](https://docs.sparklayer.io/help/pulse/receivables.md) |
| Catch accounts that are late to reorder or slipping away | [Reorder radar](https://docs.sparklayer.io/help/pulse/reorder-radar.md) and [Customers](https://docs.sparklayer.io/help/pulse/customers.md) |
| Find a product to suggest to an account | [Products](https://docs.sparklayer.io/help/pulse/products.md) |
| Get ready for a call or visit | The [prep sheet](https://docs.sparklayer.io/help/pulse/records.md#prepare-for-a-call-or-visit) |

A rep's day in Pulse:

1. **Check the Overview**: See this month's figures and who needs you today
2. **Plan the day**: Work through **Today's queue** on the Task List and add accounts to your outreach plan
3. **Prep and contact**: Open the prep sheet, then call or visit the customer
4. **Order or follow up**: Click **Order** to order for them, or log the outreach with a follow-up date

## Where Pulse fits in the Sales reps section

Pulse is one of 3 parts of the Help Center's Sales reps section:

| Part | Who it's for | Use it to |
| --- | --- | --- |
| Pulse (this part, early access) | You, the sales rep | Plan the day, follow up and keep track of your accounts. |
| [Sales rep ordering](https://docs.sparklayer.io/help/sales-ordering.md) | You, the sales rep | Take an order for a customer: in the cart, from the Catalog or at a trade counter with Counter mode. |
| [Sales rep setup](https://docs.sparklayer.io/help/sales-reps.md) | Your store owner or admin | Make someone a sales agent, and choose which customers they see and what their role lets them do. |

## Before you start

Your store owner or admin sets these up. If an account, invoice or quote is missing from Pulse, check these with them.

- **Pulse turned on for your store.** It's on every paid plan, and in early access: request it from the callout at the top of this page.
- **A sales agent account.** See [Make someone a sales agent](https://docs.sparklayer.io/help/sales-reps.md#make-someone-a-sales-agent).
- **The right customers.** Pulse shows the customers your sales agent account can see. To limit a rep to a territory, your admin uses [sales agent groups](https://docs.sparklayer.io/help/sales-reps.md#restrict-which-customers-a-sales-agent-can-see).
- **The store's accounting system connected**, such as Xero, for invoices and payment status on [Receivables](https://docs.sparklayer.io/help/pulse/receivables.md). See [Accountancy integrations](https://docs.sparklayer.io/help/integrations/accountancy.md).
- **The Quoting Engine**, for quotes on [Quotes](https://docs.sparklayer.io/help/pulse/quotes.md). See [Set up quotes](https://docs.sparklayer.io/help/ordering/quoting.md).

## Open Pulse

Pulse opens inside the SparkLayer widget when you're signed in to your store with your sales agent account.

1. Sign in to your store with your sales agent account. The SparkLayer widget opens in Sales Agent mode.
2. Click **Dashboard**. Pulse opens on the **Overview**.

### The widget's tabs

For a sales rep with Pulse, the widget has these tabs:

| Tab | What it opens |
| --- | --- |
| **Dashboard** | Pulse. |
| **Catalog** | The [Catalog](https://docs.sparklayer.io/help/sales-ordering/catalog.md), to browse and add products. Shown if your store uses the Catalog. |
| **Order** | The cart and order builder, to [order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md). |

The **My Account** tab is hidden. Use the tabs to move between Pulse and ordering. Pulse widens the widget to fit its pages. Going to **Catalog** or **Order** returns the widget to its usual width.

## Find your way round

Every Pulse page has the same frame around it:

| Part | What it shows / does |
| --- | --- |
| Sidebar | The Pulse pages, in 3 groups (see below), with **Search** above them. On a phone, tap **Menu** at the top of the page to open it. |
| **Search** | Finds accounts, orders, quotes, invoices, carts, trade applications, products and Pulse pages. Press ⌘K (Ctrl+K on Windows) on any page. See [Search Pulse](https://docs.sparklayer.io/help/pulse/records.md#search-pulse). |
| Date range | Top right of every page. Sets the period for the pages that list dated records. See [Set the date range](#set-the-date-range). |
| Side panels | Click an account, order, quote, invoice, cart or application to open it in a panel on the right, without leaving the page. See [Account, order and quote details](https://docs.sparklayer.io/help/pulse/records.md). |
| Sparkie | A bar at the foot of each page that cycles through questions about that page. Click it to ask Sparkie about your accounts. See [Ask Sparkie](#ask-sparkie). |
| **Give feedback** | At the foot of the sidebar. Sends your comments to the team building Pulse. |
| **Take the tour** | At the foot of the sidebar. Replays the guided tour. |

### The sidebar

The sidebar lists the pages in the same order as the app. A badge beside a page shows how many items need you there.

| Page | Group | Badge |
| --- | --- | --- |
| [Overview](https://docs.sparklayer.io/help/pulse/overview.md) | (top) | The accounts in **Today's queue** on the Task List. |
| [Task List](https://docs.sparklayer.io/help/pulse/task-list.md) | (top) | Tasks overdue or due today, plus customers waiting on your reply. The badge is red when any task is overdue. |
| [Activity](https://docs.sparklayer.io/help/pulse/activity.md) | (top) | None |
| [Orders](https://docs.sparklayer.io/help/pulse/orders.md), [Carts](https://docs.sparklayer.io/help/pulse/carts.md), [Quotes](https://docs.sparklayer.io/help/pulse/quotes.md), [Receivables](https://docs.sparklayer.io/help/pulse/receivables.md), [Products](https://docs.sparklayer.io/help/pulse/products.md) | **TRADE** | None |
| [Customers](https://docs.sparklayer.io/help/pulse/customers.md) | **CUSTOMERS** | Trade applications still **New** or **In review**, which you review on its **Applications** tab. |
| [Pricing](https://docs.sparklayer.io/help/pulse/pricing.md), [Reorder radar](https://docs.sparklayer.io/help/pulse/reorder-radar.md), [Retention](https://docs.sparklayer.io/help/pulse/retention.md) | **CUSTOMERS** | None |

Clicking a page in the sidebar closes any panel you have open.

## Set the date range

The date range sets the period for the pages that list dated records, such as orders, quotes and invoices.

1. Click the date range at the top right of the page. It shows the start and end dates and the number of days.
2. Choose a preset, type a **Start date** and **End date**, or click the days in the calendar.
3. Click **Apply**. To keep the range you had, click **Cancel** or press Esc.

| Presets | Options |
| --- | --- |
| **Trailing** | **Last 30 days**, **Last 90 days**, **Last 6 months**, **Last 12 months**, **Last 24 months** |
| **Calendar** | **This month**, **Last month**, **Quarter to date**, **Year to date**, **Last year** |

**More detail**

The range starts as **Last 12 months** each time Pulse loads, and stays the same as you move between pages. Type dates as 23 Jul 2025 or 2025-07-23. The start must be on or before the end, and neither date can be in the future: **Apply** stays greyed out until they are. On a large screen the calendar shows 2 months side by side; on a phone, 1.

### What the date range changes

Every page shows the date range, but only some pages use it.

| Changes with the range | Always as of today |
| --- | --- |
| [Activity](https://docs.sparklayer.io/help/pulse/activity.md), [Orders](https://docs.sparklayer.io/help/pulse/orders.md), [Quotes](https://docs.sparklayer.io/help/pulse/quotes.md) (by the day raised), [Receivables](https://docs.sparklayer.io/help/pulse/receivables.md) (by the day an invoice is dated), [Products](https://docs.sparklayer.io/help/pulse/products.md), [Customers](https://docs.sparklayer.io/help/pulse/customers.md), [Pricing](https://docs.sparklayer.io/help/pulse/pricing.md) | [Overview](https://docs.sparklayer.io/help/pulse/overview.md), [Task List](https://docs.sparklayer.io/help/pulse/task-list.md), [Carts](https://docs.sparklayer.io/help/pulse/carts.md), [Reorder radar](https://docs.sparklayer.io/help/pulse/reorder-radar.md), [Retention](https://docs.sparklayer.io/help/pulse/retention.md) |

Not every figure on those pages follows the range. For example, the **What's selling** table on Products and the lists behind the Quotes and Receivables tiles count everything, whatever the range. Each page says which of its figures follow it.

On Orders and Customers, a tile's percentage compares the range with the period of the same length just before it. Charts that follow the range have a **Period** control: **Auto** picks days, weeks or months to fit the range, or choose **Day**, **Week** or **Month** yourself.

## Where the figures come from

Pulse reads your storefront's orders and your store's connected systems. 2 labels tell you where a figure comes from:

| Label | What it means |
| --- | --- |
| **Online orders only** | The figure only counts orders placed through your storefront, by the customer or by a rep in Sales Agent mode. Orders taken by phone or email, or keyed straight into your ERP, aren't included, so a total can be lower than the account's full spend. Hover over it for the full note. |
| Source chip, such as **Orders · Shopify · Payments · Xero** (or **Source**) | Which system the order and fulfilment status, and the invoice and payment status, come from, and when each last synced. Hover over it to see the sync times. |

The source chip appears on [Orders](https://docs.sparklayer.io/help/pulse/orders.md), [Activity](https://docs.sparklayer.io/help/pulse/activity.md), [Receivables](https://docs.sparklayer.io/help/pulse/receivables.md) and on invoices. When you change an invoice's status in Pulse, your note sits beside the synced status. It doesn't change your accounting system.

**More detail**

The systems named are the ones connected to your store: your eCommerce platform for orders, and SparkLayer's Xero or QuickBooks Online integration for payments. [Receivables](https://docs.sparklayer.io/help/pulse/receivables.md) lists Shopify orders with no payment against them, and invoices from those integrations. See [Accountancy integrations](https://docs.sparklayer.io/help/integrations/accountancy.md).

## Ask Sparkie

Sparkie answers questions about your accounts, orders, quotes and products, from the same figures Pulse shows you.

1. Click the Sparkie bar at the foot of the page.
2. Click a suggested question, or type your own, such as "Where should I focus today?", and press Enter.
3. Under the answer, click an account Sparkie names to **Open account**, **Prep for visit**, start a **New order** or **Plan outreach**.

**More detail**

Each page suggests its own questions, and the panel lists up to 3 accounts under **Needs you today**. Your chats are kept under **Recent chats** in this browser. Sparkie reads only your own accounts: check its answer before you act on it. The bar hides while a side panel is open.

## Change the theme

1. Click your initials at the top right of the widget.
2. Under **Theme**, click **Light** or **Dark**.

Pulse remembers your choice.

## Take the guided tour

The tour starts the first time you open Pulse. It highlights each page in the sidebar, the main parts of the Overview, the date range, search and Sparkie, one tooltip at a time.

1. To replay it, click **Take the tour** at the foot of the sidebar, or in the menu under your initials.
2. Click **Next** and **Back** to move through it, or use the arrow keys.
3. Press Esc to leave. Next time you take the tour, it picks up where you left off, with a **Start again** link.

**More detail**

Click **Read aloud** on the first card, or the speaker on any step, to have your browser read each step out. Click it again to stop. You can't click the page while the tour is running.

## Give feedback

Pulse is in early access, so features and labels may change. Feedback goes straight to the team building Pulse.

1. Click **Give feedback** at the foot of the sidebar.
2. Under **What's it about?**, choose **Something's wrong**, **Idea**, **Question** or **Praise**.
3. Type **Your feedback**. To include a picture, click **Add a screenshot** or paste one.
4. Click **Send feedback**, or press ⌘+Enter (Ctrl+Enter on Windows).

**More detail**

For a problem, tick **This is stopping me working** if it blocks you, so the team looks at it first. Leave **You can contact me about this** ticked if you're happy for the team to reply by email. If Pulse doesn't know your email address, type it under **Your email**. Your feedback also includes the page you were on, the account you had open and your browser details, to help the team reproduce a problem. If it can't be sent, click **Copy my feedback** so you don't lose it, then **Try again**.

## Pulse pages

- [Overview](https://docs.sparklayer.io/help/pulse/overview.md): This month's figures, who needs you today and the year chart
- [Task List](https://docs.sparklayer.io/help/pulse/task-list.md): Your tasks, customer messages, today's queue and the outreach plan
- [Activity](https://docs.sparklayer.io/help/pulse/activity.md): What your customers did: orders, quotes, carts and applications
- [Orders](https://docs.sparklayer.io/help/pulse/orders.md): Find any order and see how your accounts are ordering
- [Carts](https://docs.sparklayer.io/help/pulse/carts.md): Every open cart, and the ones customers have abandoned
- [Quotes](https://docs.sparklayer.io/help/pulse/quotes.md): Open quotes, what's gone stale and what to chase
- [Receivables](https://docs.sparklayer.io/help/pulse/receivables.md): Unpaid invoices, ageing and who owes what
- [Products](https://docs.sparklayer.io/help/pulse/products.md): What's selling, by range, and who takes it
- [Customers](https://docs.sparklayer.io/help/pulse/customers.md): Your accounts, their buyers, their health and trade applications
- [Pricing](https://docs.sparklayer.io/help/pulse/pricing.md): How each customer group performs
- [Reorder radar](https://docs.sparklayer.io/help/pulse/reorder-radar.md): How often each account orders, and who is due
- [Retention](https://docs.sparklayer.io/help/pulse/retention.md): Whether accounts come back after their first order
- [Account, order and quote details](https://docs.sparklayer.io/help/pulse/records.md): The panels Pulse opens for each record, and search

## FAQs

**Which accounts does Pulse show?**

The accounts you look after: the customers your sales agent account can see. Your store owner or admin decides which customers those are. See [Restrict which customers a sales agent can see](https://docs.sparklayer.io/help/sales-reps.md#restrict-which-customers-a-sales-agent-can-see).

**Why is a total in Pulse lower than in our ERP?**

Pulse only counts orders placed through your storefront. Orders taken by phone, by email or entered straight into your ERP aren't in its figures.

**Why doesn't the date range change every page?**

Some pages show where things stand today: the Overview, Task List, Carts, Reorder radar and Retention. The date range only filters pages that list dated records, such as orders, quotes and invoices. See [What the date range changes](#what-the-date-range-changes).

**Does Pulse send emails to my customers?**

Only when you message a customer on an order or quote with **Send as email**, and **Timeline and communications** is on for your store: your message is emailed to them and shows on the order or quote in their account. See [Message the customer](https://docs.sparklayer.io/help/pulse/records.md#message-the-customer-on-an-order-or-quote) and [Order timeline and messages](https://docs.sparklayer.io/help/customers/timeline.md). Reminders for quotes and invoices are drafts for you to copy into your own email: see [Send a reminder](https://docs.sparklayer.io/help/pulse/records.md#send-a-reminder).

**Can I use Pulse on my phone?**

Yes. On a phone, the sidebar folds away: tap **Menu** at the top of the page to open it, or the search icon beside it to search. Tables show fewer columns, and some buttons, such as **Prep** on the Overview, only show on a larger screen.

## Next steps

- [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md): What happens after you click Order: build the order and check out
- [Sales rep setup](https://docs.sparklayer.io/help/sales-reps.md): For your store owner or admin: make someone a sales agent and choose their customers


---

# Overview

URL: https://docs.sparklayer.io/help/pulse/overview

Use the Pulse Overview to check this month against your typical month, see who needs you today, catch up on what's new and compare this year with last.

> **Pulse is in early access.** Request it for your sales team. [Request early access](https://feedback.sparklayer.io/get-started?choice=now). [Try the interactive demo](https://www.sparklayer.io/pulse/).

> **Quick summary**
>
> - The **Overview** is Pulse's home page. It answers 3 questions at the start of your day: how's this month going, who needs me, and what's come in?
> - It has 5 tiles, 2 tabbed panels (**Who needs you** and **Inbox**) and a chart of this year against last year. Click any tile, chart point or figure to see the orders, quotes, invoices, carts or accounts behind it.
> - The tiles and panels show where things stand today, so the date range at the top of the page doesn't change them. The chart has its own **Years** switch.
> - Open it from **Overview** at the top of the Pulse sidebar. Pulse opens on it.

The Overview's title greets you by name, such as "Welcome back" or "Good to see you", and changes each time Pulse loads. Every row on it opens its record. New to Pulse? Start with [Pulse](https://docs.sparklayer.io/help/pulse.md).

## The Overview screen

From top to bottom:

| Part | What it shows / does |
| --- | --- |
| Tiles | 5 figures across the top: **Your month**, **Carts in progress**, **Open quotes**, **Overdue invoices** and **Reorders waiting**. Click one to see what makes it up. |
| **Sparkie insights** | A sentence summing up what's waiting for you today. |
| **Who needs you** | Accounts and people to act on, in 5 tabs: **Due**, **Messages**, **Slipping**, **Tasks** and **Vs** last year. |
| **Inbox** | What has come in, in tabs: **New**, **Quotes**, **Applications** and **Carts**. |
| **Your book** chart | Your accounts' orders this year against last year, with filters. Under it, 5 figures for the year so far. |

On a large screen, **Who needs you** and **Inbox** sit side by side; on a smaller one, one above the other.

## The tiles

Each tile is one figure you can act on. Click it to see what makes it up.

| Tile | What it shows | Click it to see |
| --- | --- | --- |
| **Your month** | The value of orders so far this month, the number of orders, and your typical month (**typical \~**). The percentage compares this month with your typical month at the same day: the average of the last 3 months, each counted up to the same day of the month. | **Your month so far**: the month's orders |
| **Carts in progress** | The value of carts customers have started but not ordered, in your store's currency, then how many are open and how many are abandoned. | Every cart |
| **Open quotes** | The value of quotes waiting for a decision (**Open** or **Awaiting customer**), and how many. | Each open quote, largest first |
| **Overdue invoices** | The value of unpaid invoices past their payment terms, and how many. | Each overdue invoice, most overdue first |
| **Reorders waiting** | The value of the usual baskets of accounts due today or overdue to reorder, and how many accounts. | Every account due in the next 7 days |

An account's **usual basket** is what its next order is likely to be, at its own prices: the products it orders in at least half of its orders, each at its usual quantity. It's what Pulse puts in the basket when you click **Order**. See [how the usual basket is worked out](https://docs.sparklayer.io/help/pulse/reorder-radar.md#how-the-figures-are-worked-out) on Reorder radar.

**More detail**

**Carts in progress** only adds up carts in your store's currency. Carts in another currency show beside the value instead, such as **+€1.4k** or **+2 currencies**: hover over it to see them. They aren't converted, so they aren't in the total.

A cart counts as abandoned when nobody has touched it for 3 days. To change that, use **Abandoned after** on [Carts](https://docs.sparklayer.io/help/pulse/carts.md#change-when-a-cart-counts-as-abandoned).

The **Reorders waiting** breakdown also lists accounts due in the next 7 days, so it can show more accounts, and a larger total, than the tile.

A breakdown opens in a panel on the right. For orders, it lists them by account and in a table, with a total. Click a row to open it. See [Account, order and quote details](https://docs.sparklayer.io/help/pulse/records.md#a-breakdown).

### Sparkie insights

Under the tiles, **Sparkie insights** sums up your day in one sentence: how many accounts are due to reorder and what they're worth, and how many open quotes and overdue invoices are waiting. Click **See the full insight** to ask Sparkie "Where should I focus today?". See [Ask Sparkie](https://docs.sparklayer.io/help/pulse.md#ask-sparkie).

## Who needs you

**Who needs you** lists the accounts and people to act on today, in 5 tabs. A number on a tab shows how many need you.

| Tab | What it lists |
| --- | --- |
| **Due** | Accounts due to reorder in the next 7 days, measured against each account's own rhythm: the most overdue first, then by usual basket. Each shows how late or soon it is, such as **3d overdue**, **due today** or **due in 2d**, and its usual basket. The tab's number counts only the accounts due today or overdue. |
| **Messages** | Customers waiting on your reply on an order or quote, longest wait first, with their last message. Click **Reply on order** or **Reply on quote** to open it at its timeline, ready to reply. See [Reply to customer messages](https://docs.sparklayer.io/help/pulse/task-list.md#reply-to-customer-messages). |
| **Slipping** | Accounts showing a warning sign, each with its health score and up to 2 reasons. See [Why an account is slipping](#why-an-account-is-slipping). |
| **Tasks** | Your open tasks with a due date: overdue first, then due today, then upcoming. Click the circle to mark one done, or the bin to delete it. The tab's number counts tasks overdue or due today. |
| **Vs** last year, such as **Vs 2025** | How each account is trading from 1 January to today, against the same dates last year, in money and percentage. Accounts trading down are listed first, biggest fall first. |

Each tab shows 5 rows at a time. To see the rest, click the link at the foot of the list, such as **Show 3 more**. Click an account's name to open it. The link at the foot of each tab goes to the full page:

| Tab | Link |
| --- | --- |
| **Due** | **Reorder radar** |
| **Messages** | **All messages**, on the Task List |
| **Slipping** and **Vs** | **All customers** |
| **Tasks** | **All tasks** |

### Order or prepare from the Due tab

Each account on the **Due** tab has 2 buttons:

- **Prep** opens the [prep sheet](https://docs.sparklayer.io/help/pulse/records.md#prepare-for-a-call-or-visit): what they buy, what they owe and what to raise on the call. It only shows on a larger screen.
- **Order** starts an order for them with their usual basket in the cart, ready for you to check. See [Order for the customer](https://docs.sparklayer.io/help/pulse/records.md#order-for-the-customer).

### Why an account is slipping

An account is slipping when any of these apply. Its reasons show as labels, the most serious first. The figures in the labels are examples:

| Label | When it shows |
| --- | --- |
| **Quiet 45 days** | The account hasn't ordered for 2.5 times its usual gap and more than 30 days. Without a usual gap, it has 3 or more orders and hasn't ordered for 91 to 540 days. |
| **Reorder 12d late** | It's at least 3 days past its usual gap, and isn't quiet. |
| **Health -6 this week** | Its health score is lower than 7 days ago. |
| **Avg order $420 · −15% vs prior 90d** | Its average order over the last 90 days is more than 10% below the 90 days before (or below its all-time average, shown as **vs their norm**). |
| **Spend −20% vs prior 90d** | It spent more than 10% less in the last 90 days than in the 90 days before, and isn't quiet. |

Accounts with the most serious reasons come first. An account needs orders on 3 separate days before it has a usual gap. Accounts that have been invited but haven't ordered yet are left out.

**More detail**

An account's health score runs from 0 to 100, with a band: **Healthy** (75 and above), **Stable** (50 to 74), **At risk** (30 to 49) or **Critical** (below 30). It comes from how recently it ordered against its usual gap, whether its spend is holding up and how many orders it has placed. Hover over the score for the rules. See [How account health is scored](https://docs.sparklayer.io/help/pulse/customers.md#how-account-health-is-scored).

### Trading against last year

On the **Vs** tab, an account is trading up or down when its spend has changed by 5% or more. Each shows its spend this year and last, and a label: the change in money and percentage, or **New this year** if it bought nothing by this date last year. The tab's number counts accounts trading down. The tab counts online orders only.

## Inbox

**Inbox** shows what's come in. Click a row to open the record itself.

| Tab | What it lists |
| --- | --- |
| **New** | What your customers did since you last caught up, newest first: **Order placed**, **Order shipped**, **Quote raised**, **Cart in progress** or **Cart abandoned**, **Trade application**, and replies on orders and quotes. The first time you open Pulse, it shows the last 7 days. |
| **Quotes** | Open quotes, largest first, with when each was raised and how many days it has been open. A quote open 14 days or more is marked **stale**. |
| **Applications** | Trade applications that are **New** or **In review**. Click **Contact** to add a task to call the applicant today, which also moves a **New** application to **In review**. Click **Review** to open the application. |
| **Carts** | Every open cart, most recently touched first, marked **In progress** or **Abandoned · 4d** (untouched for 4 days). |

The link at the foot of each tab goes to the full page: **Activity**, **View all** (Quotes), **Customers** or **Carts**.

### Mark as caught up

When you've read the **New** tab, click **Mark as caught up** at its foot. The tab clears, and new activity collects there again.

## Use the year chart

The **Your book** chart shows your accounts' orders across the year. This year is a solid line that stops at today, and last year a dashed line for the whole year. The title says what it's showing, for example **Your book — 2026 vs 2025**.

1. To see one account, click **Customer: All** and choose it. The list shows your 5 busiest accounts: search to find the rest.
2. To see one product range, click **Product: All** and choose it. The chart then counts only that range's lines, and **Show** gains **Units**.
3. To look at last year against the year before, click **Years** and choose the earlier pair.
4. To change the buckets, click **Period** and choose **Day**, **Week** or **Month**.
5. To chart something other than order value, click **Show** and choose **GMV**, **Orders** or **Avg order value**.
6. Click a point on the chart to see this year's orders in it.

**More detail**

You can combine the **Customer** and **Product** filters, for example to see one account's orders of one range against last year. GMV (gross merchandise value) is the total value of orders. The chart counts online orders only: see [Where the figures come from](https://docs.sparklayer.io/help/pulse.md#where-the-figures-come-from).

### The figures under the chart

The 5 figures under the chart use the same customer and product filters as the chart. Click a figure to see the orders behind it. Each percentage compares with the same dates last year.

| Figure | What it shows |
| --- | --- |
| **Month to date · vs typical** | This month's orders so far, against your typical month at the same day. With a filter, it reads **Month to date** and shows the number of orders instead. |
| **Year to date** | Orders from 1 January to today. |
| **Orders** | The number of orders over the same period. |
| **Avg order value** | The average order value over the same period. |
| **Active buyers** | How many accounts ordered. With a **Product** filter, this shows **Units** instead. |

**More detail**

**Month to date** is always this month, whichever **Years** pair you choose.

## If you're a sales manager

Signed in as a sales manager, you see the whole store in Pulse, not one rep's accounts, and the Overview adds a summary of each sales agent. The first tile reads **Company month**: the store's orders this month against its typical month. Under the tiles, a **By rep** card ranks each sales agent by this month's sales, with their accounts, orders this month and a percentage against their own typical month. Reps with no orders this month are grouped in one line: click it to see their names. Click the arrow to fold the card away.

## FAQs

**Why doesn't the date range change the Overview?**

The Overview shows where things stand today: this month, what's open now and who is due now. To look at a past period, use [Orders](https://docs.sparklayer.io/help/pulse/orders.md) or [Activity](https://docs.sparklayer.io/help/pulse/activity.md), or use the chart's **Years** switch.

**Why is Reorders waiting different from the average order value?**

**Reorders waiting** adds up each due account's usual basket, which is what their next order is likely to contain. The average order value includes one-off and unusually large orders, so it can be higher or lower.

**Why does the Reorders waiting breakdown show more accounts than the tile?**

The tile counts accounts due today or overdue. The breakdown also lists accounts due in the next 7 days, so you can plan ahead.

**How does Pulse decide an account is due?**

From the account's own rhythm: the usual gap between its orders, once it has orders on 3 or more separate days. An account that orders every 3 weeks is due 3 weeks after its last order. See [Reorder radar](https://docs.sparklayer.io/help/pulse/reorder-radar.md).

**Why is an account trading down when its orders look fine?**

The **Vs** tab compares 1 January to today with the same dates last year, and counts online orders only. A large order last year, or orders placed by phone or in your ERP this year, can make an account look lower.


---

# Task List

URL: https://docs.sparklayer.io/help/pulse/task-list

Keep on top of follow-ups in Pulse: add, complete and export tasks, reply to customer messages, work through today's queue and log calls and visits.

> **Pulse is in early access.** Request it for your sales team. [Request early access](https://feedback.sparklayer.io/get-started?choice=now). [Try the interactive demo](https://www.sparklayer.io/pulse/).

> **Quick summary**
>
> - The **Task List** in Pulse plans your day, in 3 tabs: **All tasks** (every follow-up you've promised, each linked to an account), **Messages** (customers waiting on your reply) and **Today's queue** (who to call or visit today).
> - **All tasks** groups open tasks as overdue, due today and upcoming. Add, complete, delete, search and export them as CSV, Markdown or plain text.
> - **Today's queue** suggests up to 12 accounts to contact today and why. Add them to your **Outreach plan**, prepare with the prep sheet, then log how it went.
> - On a phone, today's queue becomes a stack of cards with **Call**, **Directions** and **Prep** buttons, for working on the road.

## How the Task List works

Open it from **Task List** in the Pulse sidebar. The badge on it counts tasks that are overdue or due today, plus customers waiting on a reply. It turns red when any task is overdue.

| Tab | What it shows | Its count |
| --- | --- | --- |
| **All tasks** | Your tasks, with a **View** menu, search, **Export** and **Add task**. | Open tasks. |
| **Messages** | Orders and quotes your customers have written on. See [Reply to customer messages](#reply-to-customer-messages). | Customers waiting on your reply. |
| **Today's queue** | Who to work today, beside your **Outreach plan**. | Accounts in the queue. |

A task is **Overdue** once its due date has passed, **Due today** on its date and **Upcoming** before then. The Task List is always as of today: the date range at the top of the page doesn't change it.

## Work through today's queue

**Who to work today**, on the **Today's queue** tab, lists up to 12 accounts most worth contacting today, a row for each, each with its health score, the reason and what they usually spend.

1. Click the **Today's queue** tab.
2. Click **Today** on an account to add it to your **Outreach plan**. It then shows **Planned**.
3. Click **Prep** to read the [prep sheet](https://docs.sparklayer.io/help/pulse/records.md#prepare-for-a-call-or-visit) before you call or visit.
4. Click **Order** to order for the customer, starting from their usual basket. For a customer waiting on a reply, click **Reply** instead.

The queue is in this order, with the longest wait or the most overdue first:

| Reason, for example | When an account is listed |
| --- | --- |
| **Reply waiting · #1042** | The customer wrote last on one of their orders or quotes. |
| **Promised 2 days ago** or **Follow-up due today** | The account has an open task. It reads **Promised…** once the task is past its date. |
| **#1042 stuck 21 days** | Their latest order has been processing for at least 7 days, and at least 3 times as long as their orders usually take. |
| **6 days overdue** | They're at least 3 days past their usual time between orders. Only for accounts with orders on 3 or more separate days. |
| **Quiet 60 days** | They've gone at least 2.5 times their usual gap between orders without ordering, and more than 30 days. For an account without a regular rhythm, 91 days or more. Accounts quiet for more than 540 days aren't listed. |

With nothing pressing, the queue suggests the 5 accounts with the highest average order, as **Last ordered 12d ago** or **Worth a touch-base**.

**More detail**

Once you've logged outreach to an account today, it leaves the queue, unless the customer is waiting on a reply. Accounts with the same priority are ordered by their average order value. **Order** opens the order in your storefront, signed in as the customer, with their usual basket: see [Account, order and quote details](https://docs.sparklayer.io/help/pulse/records.md#order-for-the-customer).

## Plan your outreach

The **Outreach plan**, beside the queue, is the list of accounts you mean to contact today. It shows how many you've done so far, such as **1 of 3 done**.

1. Click **Plan outreach**, search your accounts by name or email, and click the one to add. Or, while the plan is empty, click **Plan** on one of the 3 accounts it suggests from the queue.
2. When you've spoken to them, click **Log** and record how it went. The account is struck through and marked **Done**, with the outcome underneath.
3. To take an account off the plan without logging anything, click the cross, then **Remove**. Anything you've already logged against them stays.

You can also add an account from its panel: open it and click **Actions** > **Plan outreach** at the foot. The plan is for today: tomorrow it starts empty.

## Log outreach

Log each call or visit so your plan, tasks and the account's timeline stay up to date.

1. Click **Log** in the outreach plan, or **Log outreach** on an account, a prep sheet or a card on your phone.
2. Under **How did it go?**, choose **Ordered**, **Quoted**, **No order** or **Couldn't see them**.
3. Optionally, enter the **Order value** or **Quote value**, add **Notes** and choose a **Follow up on** date.
4. Click **Save**.

**More detail**

Logging outreach marks the account as done in today's plan (adding it if it wasn't there), completes every open task for that account, and records the visit on the account's **Timeline**, such as **Visit logged · placed an order**. A **Follow up on** date adds a new task on that date, with your notes as its text. The value field only shows for **Ordered** and **Quoted**.

## Work on the road

On a phone, **Today's queue** shows each account as a card, with the contact's name, phone number and address, what their usual basket is worth, and large buttons:

| Button | What it does |
| --- | --- |
| **Call** | Calls the contact's number. Shows **No number** if there isn't one on file. |
| **Directions** | Opens the address in your maps app. Only shows when there's an address. |
| **Prep** | Opens the [prep sheet](https://docs.sparklayer.io/help/pulse/records.md#prepare-for-a-call-or-visit). |
| **Today** | Adds the account to your outreach plan. Once it's on the plan, this becomes **Log outreach**. For a customer waiting on a reply, it's **Reply**. |

## Reply to customer messages

Customers can write to you on their orders and quotes. The **Messages** tab collects those conversations, so nobody waits on an answer.

1. Click the **Messages** tab. **Waiting on you** lists the conversations where the customer wrote last, longest wait first.
2. Click **Reply on order** or **Reply on quote**. The order or quote opens at its timeline, ready for your reply.
3. Write your reply and click **Send as email**. It's emailed to the customer and shows on the order or quote in their account, when **Timeline and communications** is on for your store. See [Order timeline and messages](https://docs.sparklayer.io/help/customers/timeline.md).

To see every conversation, including ones you've answered, click **All conversations**: they're listed newest message first, with **Open order** or **Open quote**. Each row shows who wrote last, what they said, when, and how long the customer has been waiting, such as **Waiting 2 days**. With nobody waiting, the tab shows **You're all caught up**. To leave a note on the order or quote that only your team sees, click **Internal note** instead of writing to the customer.

## Add a task

1. On the **All tasks** tab, click **Add task**.
2. Click **Customer** and choose the account. It lists the 5 accounts with the most orders: search to find others.
3. Change the date if it isn't due today, and type what needs doing.
4. Click **Add task**.

**More detail**

Every task needs an account: without one, Pulse asks you to choose a customer. You can also add a task from an account: open it, go to its **Tasks & Notes** tab and click **Add task**. There you can add **Notes** for whoever picks it up, and tick **Share with everyone** so it shows in every rep's Task List. Otherwise only you see it. The Task List shows the task itself, not its notes.

## Complete a task

Click the circle at the start of the task (**Mark done**). It moves to **Done**, marked with today's date. To see finished tasks, choose **Done** in the **View** menu.

A done task can't be reopened. If there's more to do, add a new task.

## Find a task

1. Type an account name or a word from the task in the search box (**Account or task…**).
2. To narrow the list, click **View** and choose a view.

| View | Shows |
| --- | --- |
| **Open** | Every open task, grouped as **Overdue**, **Due today**, **Upcoming** and **No date**. |
| **Overdue** | Open tasks past their date, oldest first. |
| **Due today** | Open tasks due today. |
| **Upcoming** | Open tasks due after today, soonest first. |
| **Done** | Tasks you've completed. |

Each view shows how many tasks are in it. Every view except **Open** shows 20 tasks a page. Click an account name or a task to open the account on its **Tasks & Notes** tab, or **Prep** for its [prep sheet](https://docs.sparklayer.io/help/pulse/records.md#prepare-for-a-call-or-visit).

## Delete a task

1. Click the bin icon at the end of the task (**Delete this task**).
2. Click **Delete task** to confirm. The task is removed from every list, and this can't be undone.

Delete a task that no longer matters, such as a follow-up for an order that came in another way. You can delete done tasks too.

## Export your tasks

1. Click **Export**.
2. Under **Download**, choose **CSV**, **Markdown** or **Plain text**.

The file, such as `pulse-tasks-2026-10-19.csv`, lists every task, open and done, by due date, whatever view or search you have on screen. It has 4 columns: **Due**, **Account**, **Task** and **Status** (**Done**, **Overdue**, **Due today** or **Upcoming**). Use CSV for a spreadsheet, or Markdown or plain text to paste into notes or an email.

## How tasks get on the list

You add most tasks yourself. Pulse also adds one when you:

| Action | Task added |
| --- | --- |
| Log outreach with a **Follow up on** date | A follow-up on that date, with your notes. |
| Mark a quote or invoice reminder as sent | A check 3 days later, such as "Check quote QT-118 after the reminder". See [Send a reminder](https://docs.sparklayer.io/help/pulse/records.md#send-a-reminder). |
| Click **Contact** on a trade application in the Overview, or **Add a task to call** on the application | A call to the applicant today, with their name, company and phone number. |
| Click **Add a nudge task** on a cart | A nudge today about the basket they left, with its value and number of lines. |
| Click **Add a task** on an invoice | A reminder today to chase it, such as "Chase invoice INV-1001 — $540, 12d overdue". |
| Click **Add to Task List** in the **Action plan** on Reorder radar | A reorder call for each account that's due, overdue or quiet. See [Reorder radar](https://docs.sparklayer.io/help/pulse/reorder-radar.md). |

## FAQs

**How do I get my tasks into another app?**

[Export them](#export-your-tasks) as CSV, Markdown or plain text, then import or paste them into the other app. **Microsoft To Do** and **HubSpot** are listed under **Send to** in the **Export** menu as **Coming soon**.

**Does the date range change the Task List?**

No. Tasks, messages, today's queue and the outreach plan are always as of today.

**Why did an account leave today's queue?**

It leaves once you've logged outreach to it today, unless the customer is waiting on a reply. Other accounts move up to take its place.

**Can I undo marking a task as done?**

No. A done task stays done. Add a new task if there's still something to do, or delete the done one if you don't want it on the list.

**Who can see my tasks?**

Only you, unless you share one. Tasks belong to the rep who made them. When you add a task from an account's **Tasks & Notes** tab, tick **Share with everyone** to show it in every rep's Task List.

**Can I see my tasks on another device?**

No. Your tasks and notes are saved in the browser you use, so they don't follow you to another device or browser. To take a copy with you, [export your tasks](#export-your-tasks).


---

# Activity

URL: https://docs.sparklayer.io/help/pulse/activity

See what your customers did in Pulse's Activity feed: orders placed and shipped, quotes raised, carts, trade applications and messages to you.

> **Pulse is in early access.** Request it for your sales team. [Request early access](https://feedback.sparklayer.io/get-started?choice=now). [Try the interactive demo](https://www.sparklayer.io/pulse/).

> **Quick summary**
>
> - **Activity** in Pulse is a feed of what your customers did: orders placed and shipped, quotes raised, carts in progress or abandoned, trade applications and messages on orders and quotes.
> - Use **Show** to pick the kinds of activity, and the date range at the top of the page to set the period. It starts at the last 12 months.
> - Click a row to open the order, quote, cart or application. Click the account name in it to open the account.
> - Your own calls, visits and tasks aren't in the feed. They're on each account's **Timeline**.

Open it from **Activity** in the Pulse sidebar. Use it to catch up on what's happened across your accounts, newest first. For only what's new since your last visit, see the **New** tab of the [Overview](https://docs.sparklayer.io/help/pulse/overview.md#inbox)'s **Inbox**.

## The Activity screen

| Part | What it shows / does |
| --- | --- |
| **Customer activity** | The feed, newest first, 15 rows a page. The heading shows the period, such as **last 12 months**, or the dates of a custom range. Use **Previous** and **Next** to page through. |
| Rows | What happened, which account, the value (for orders, quotes and carts) and the date. A message row also shows what the customer wrote. |
| **Show** | Choose which kinds of activity to list. Each option shows how many there are in the period. With none chosen, it shows **All**. |
| **Source** | Where order details come from, such as your eCommerce platform, and when they last synced. Hover over it to check. |

With nothing in the period, the feed shows **Nothing in this window.**

## What the feed shows

The feed lists 5 kinds of activity. Each row opens the record behind it.

| Kind | Rows | Opens |
| --- | --- | --- |
| **Orders** | Each order once, on the day it was placed: **Order placed** while it's processing, **Order shipped** once it has shipped, with the order number. | The [order](https://docs.sparklayer.io/help/pulse/records.md#an-order) |
| **Quotes** | **Quote raised**, with the quote reference and its status, such as **open** or **accepted** | The [quote](https://docs.sparklayer.io/help/pulse/records.md#a-quote) |
| **Carts** | **Cart in progress** or **Cart abandoned**, with the number of lines and where it was built, such as the storefront or quick order, on the day it was last changed | The [cart](https://docs.sparklayer.io/help/pulse/records.md#a-cart-in-progress) |
| **Forms** | **Trade application**, with the business name, the contact's name and the application's status | The [application](https://docs.sparklayer.io/help/pulse/records.md#a-trade-application) |
| **Messages** | **Replied on order** or **Replied on quote**, with what the customer wrote | The order or quote, at its timeline, so you can reply |

A cart counts as abandoned once nobody has touched it for 3 days, or the number of days chosen under **Abandoned after** on the **Carts** page. Messages are only the customer's: your own replies and internal notes aren't listed.

## Filter the feed

Narrow the feed to the activity you care about, or to a different period.

1. Click **Show** and choose the kinds you want, such as **Quotes** and **Carts**. You can choose more than one.
2. To change the period, click the date range at the top right of the page and choose a range.

**More detail**

The Activity feed only lists orders placed through your storefront. See [Where the figures come from](https://docs.sparklayer.io/help/pulse.md#where-the-figures-come-from).

## Open a record

1. Click a row to open the order, quote, cart or application in a panel. A message row opens the order or quote at its timeline.
2. To open the account instead, click the account name in the row. Trade applications don't have an account yet, so their name isn't a link.

From the panel you can act on the record, for example finish a customer's cart for them or approve an application. See [Account, order and quote details](https://docs.sparklayer.io/help/pulse/records.md).

## FAQs

**Why don't I see my calls and visits?**

Activity is for what customers did. Your logged outreach, tasks and reminders are on each account's **Timeline**, with the customer's orders and quotes. See [The account timeline](https://docs.sparklayer.io/help/pulse/records.md#the-account-timeline).

**Why is an order missing?**

Check the date range covers the day it was placed and that **Orders** is ticked under **Show**. Orders placed outside your storefront don't appear in Pulse.

**Where do I answer a customer's message?**

Click the message row to open the order or quote at its timeline, and reply there. To see every customer waiting on a reply, use the **Messages** tab of the [Task List](https://docs.sparklayer.io/help/pulse/task-list.md#reply-to-customer-messages).


---

# Orders

URL: https://docs.sparklayer.io/help/pulse/orders

Use the Orders screen in Pulse to see how much your accounts order, find any order by buyer or number, and open it to reorder or check its invoice.

> **Pulse is in early access.** Request it for your sales team. [Request early access](https://feedback.sparklayer.io/get-started?choice=now). [Try the interactive demo](https://www.sparklayer.io/pulse/).

> **Quick summary**
>
> - **Orders** in Pulse answers "how are my accounts ordering?" and "where's that order?": 4 headline figures, a chart over time and a searchable table of every order in the date range.
> - Open it from the Pulse sidebar, under **TRADE**. The date range at the top of the page sets the period for everything on the screen.
> - Click a figure, a point on the chart or a row to see the orders behind it, then reorder or open the invoice from the order.
> - Figures cover orders placed through your storefront only, not orders taken by phone, by email or keyed into your ERP.

The figures at the top tell you whether orders and spend are up or down on the previous period. The table below lets you find a single order and act on it.

New to Pulse? Start with [Pulse](https://docs.sparklayer.io/help/pulse.md) for how to open it and how the date range works.

## The Orders screen

The screen has tiles, a chart and a table of orders, all for the date range.

| Part | What it shows / does |
| --- | --- |
| **Orders**, **GMV**, **Avg order value** and **Active buyers** tiles | The totals for the date range, each with a small monthly trend line and the change on the previous period. Click a tile to list the orders behind it. **Active buyers** lists the accounts that ordered instead, largest spend first. |
| **Orders & GMV over time** | A chart of the number of orders and their value across the date range. Choose the **Period** (**Auto**, **Day**, **Week** or **Month**). Click a point to list the orders in it. |
| Month comparison strip | Under the chart: GMV for the current month so far, then for the months 1, 3, 6 and 12 months ago, as far back as the date range goes, each with a percentage change. |
| **All orders** table | One row per order, newest first: **Date**, **Order #**, **Buyer**, **Items** (number of lines), **Status**, **Payment** and **Value**. 20 orders a page, with **Previous** and **Next**. Click a row to open the order. |
| **Status** filter | Show **Shipped** or **Processing** orders, or both. The menu shows how many of each there are. |
| **Payment** filter | Show **Paid** or **Pending** orders, or both. |
| Search | Type a buyer name or an order number (**Buyer or order #…**). |
| **Source** | Where order and payment details come from (your eCommerce platform and your accounting system) and when each last synced. Hover over it to see the sync times. |
| **Online orders only** | A reminder that the figures only include storefront orders. Hover over it for details. |
| **Download CSV** | Saves every order in the table, with your filters and search applied, as a CSV file. |

## Find an order

1. In Pulse, click **Orders** in the sidebar.
2. Set the date range to a period that includes the order.
3. Type the buyer's name or the order number in the search box.
4. Click the order to open it.

**More detail**

To narrow the list instead, use the **Status** and **Payment** filters, for example **Processing** and **Pending** to see orders that haven't shipped or been paid. You can also press ⌘K (Ctrl+K on Windows) anywhere in Pulse and type an order number to jump straight to it. The order opens in a panel with its lines and links to its account and invoice: see [An order](https://docs.sparklayer.io/help/pulse/records.md#an-order).

## See the orders behind a figure

1. Click a tile, such as **GMV**, or a point on the **Orders & GMV over time** chart. Pulse lists the orders that make up that figure, with each account's share of the total.
2. Click an order to open it.

## Reorder for a customer

1. Find the order and click it to open it.
2. Click **Reorder**. Pulse opens the order builder, signed in as the customer, with the same lines in a new order.
3. Check the quantities and place the order.

**More detail**

The order panel also has **New order** (an empty basket for the same account), **Reorder their usual** (the products they usually order, at their usual quantities), **Open buyer profile** and **View invoice**, if the order has an unpaid invoice. See [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md) for how the order builder works.

## How the figures are worked out

| Figure | How it's worked out |
| --- | --- |
| Which orders are counted | Orders placed in the date range, by order date. Quotes are never counted as orders. |
| **Orders** | The number of orders placed in the date range. |
| **GMV** | Gross merchandise value: the total value of those orders, including tax and shipping. |
| **Avg order value** | GMV divided by the number of orders, so it also includes tax and shipping. |
| **Active buyers** | The number of accounts that placed at least one order in the date range. |
| Change on a tile | The same figure for the period of the same length immediately before the date range. Hover over the percentage to see this. |
| **Period** | **Auto** picks days for a range of up to 31 days, weeks for up to 120 days, and months for anything longer. |
| Month comparison strip | When the current month isn't finished, it shows the month so far without a change. The last full month shows its change on the month before it. The other months show how the last full month compares with them. |
| **Status** | The order's fulfilment status from your eCommerce platform: **Processing** or **Shipped**. |
| **Payment** | The payment status from your accounting system: **Paid** or **Pending**. A dash means there's no payment status for the order. |

Orders only counts orders placed through your storefront, so a total can be lower than the account's full spend. See [Where the figures come from](https://docs.sparklayer.io/help/pulse.md#where-the-figures-come-from).

## FAQs

**Why is an order missing?**

Check the date range covers the day the order was placed, and clear any **Status** or **Payment** filter and the search box. Orders placed outside your storefront, such as by phone or in your ERP, don't appear in Pulse.

**Can I sort the orders table?**

No. The **All orders** table always lists the newest orders first. To find a particular order, search by buyer or order number, or use the **Status** and **Payment** filters. To sort another way, click **Download CSV** and sort the file in a spreadsheet.

**Does GMV include tax and shipping?**

Yes. **GMV** and **Avg order value** are worked out from each order's full value, including tax and shipping.

**Why does the payment status differ from my accounting system?**

Payment status is synced from your accounting system on a schedule. Hover over **Source** to see when it last synced.

**What's the difference between Avg order value and an account's usual basket?**

**Avg order value** is what orders have been worth on average. An account's usual basket is what their next order is likely to be, and Pulse uses it wherever it predicts an order. See [how the usual basket is worked out](https://docs.sparklayer.io/help/pulse/reorder-radar.md#how-the-figures-are-worked-out) on Reorder radar.


---

# Carts

URL: https://docs.sparklayer.io/help/pulse/carts

See every open cart across your accounts in Pulse, spot the abandoned ones, set when a cart counts as abandoned and finish a cart for the customer.

> **Pulse is in early access.** Request it for your sales team. [Request early access](https://feedback.sparklayer.io/get-started?choice=now). [Try the interactive demo](https://www.sparklayer.io/pulse/).

> **Quick summary**
>
> - **Carts** in Pulse lists every cart your accounts have started and not ordered yet: what's in them, what they're worth and which have stalled.
> - Open it from the Pulse sidebar, under **TRADE**. Carts are shown as they stand today: the date range doesn't change this page.
> - A cart counts as abandoned once nobody has changed it for 3 days. Change that with **Abandoned after**.
> - Open a cart to take it over with **Finish it for them** and place the order, add a task to nudge the customer, or prepare for a call.

A cart with products in it is an order that hasn't happened yet. **Carts** shows you every one across your book, so you can call about a large basket before it goes cold, or place the order for the customer.

New to Pulse? Start with [Pulse](https://docs.sparklayer.io/help/pulse.md) for how to open it and how the date range works.

## How it works

Carts come from your store's live data. A cart is listed once a customer, or a rep signed in as them, adds a product to it, and leaves the **Carts** page once it's ordered. Each cart has a status:

| Status | Meaning |
| --- | --- |
| **In progress** | Changed within the abandoned rule: someone is still working on it. |
| **Abandoned · 4d** (for example) | Nobody has changed it for at least the number of days in **Abandoned after**. The number is how many days it has sat untouched. |

## The Carts screen

3 tiles sum up the carts. The **Open carts** table lists each one.

| Part | What it shows / does |
| --- | --- |
| **Value in carts** tile | The total value of every open cart, and how many there are. Click it to list every cart. |
| **In progress** tile | How many carts have changed within the abandoned rule, such as **Changed in the last 3 days**. Click it to list them. |
| **Abandoned** tile | How many carts have sat untouched for the abandoned rule or longer, such as **Untouched for 3 days or more**. Click it to list them. |
| **Open carts** table | One row per cart: **Customer**, **Status**, **Lines**, **Units**, **Started**, **Last change** and **Value**. 20 carts a page, with **Previous** and **Next**. Click a row to open the cart. |
| **Customer** | The account, with its email, the company location the cart was built for, if any, and **Built by a rep** when a rep built it for the customer. |
| **Last change** | How long ago the cart was last changed, with the date. |
| **Value** | The cart's total, in the currency the customer is buying in. |
| **Status** filter | Show **All** carts, or only **In progress** or **Abandoned** ones. The menu shows how many of each there are. |
| **Abandoned after** | How many days without a change make a cart abandoned: **1 day**, **2 days**, **3 days**, **5 days**, **7 days**, **14 days** or **30 days**. See [Change when a cart counts as abandoned](#change-when-a-cart-counts-as-abandoned). |
| **Source** | Hover over it for what the list includes and how the abandoned rule works. |
| **Download CSV** | Saves every cart in the table, with your status filter applied, as a CSV file. |

On a phone, the table shows only **Customer** and **Value**, with the status under the customer's name.

## Find the carts worth chasing

1. In Pulse, click **Carts** in the sidebar.
2. Click **Value** to sort the biggest carts first, or **Last change** to sort by how long each has sat.
3. To see only stalled carts, click **Status** and choose **Abandoned**.
4. Click a cart to open it.

**More detail**

The table starts sorted by **Last change**, most recent first. You can sort by **Lines**, **Units**, **Started**, **Last change** or **Value**. The first click on a heading puts the biggest or most recent first, and the next click reverses it. An arrow shows which column the table is sorted by. On a phone, only **Value** sorts.

## Change when a cart counts as abandoned

1. Click **Abandoned after**.
2. Choose the number of days, such as **7 days**.

Every cart is re-checked straight away. The new rule also applies to the **Carts in progress** tile and the **Carts** tab of the **Inbox** on the [Overview](https://docs.sparklayer.io/help/pulse/overview.md), to [Activity](https://docs.sparklayer.io/help/pulse/activity.md) and to the cart panel, so they all count the same carts. Your choice is saved in the browser you use, so it doesn't follow you to another device or browser.

## Finish a cart for the customer

1. Open the cart and click **Finish it for them**.
2. Pulse signs you in as the customer and takes over their cart, with its lines in the basket.
3. Change the order if you need to, then place it.

Once it's ordered, the cart leaves the **Carts** page. See [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md) for how the order builder works.

## Nudge the customer

1. Open the cart and click **Add a nudge task**.
2. Pulse adds a task for today to your [Task List](https://docs.sparklayer.io/help/pulse/task-list.md), such as "Nudge about the $270 basket left in the cart (2 lines)".

To prepare for the call, click **Call prep** on the cart. It opens the account's call prep sheet: see [Prepare for a call or visit](https://docs.sparklayer.io/help/pulse/records.md#prepare-for-a-call-or-visit).

## The cart panel

Click a cart anywhere in Pulse to open it in a panel.

| Part | What it shows |
| --- | --- |
| Header | **Cart ·** and the account's name, its status, the cart's reference, the account and where it was built. |
| **In the basket** | Each line: product, SKU, quantity, unit price and line total, with the **Basket total**. Click a product to open it. |
| **Timing** | **Started**, **Last touched** (in red when the cart is abandoned), **Built in** (such as **Storefront** or **Quick order**) and **Vs their usual**: how the cart's value compares with the account's average order. Underneath, **Untouched 4 days · abandoned** or **Touched yesterday · live**, for example. |
| Buyer | The account, with a link to its full profile. |

See also [A cart in progress](https://docs.sparklayer.io/help/pulse/records.md#a-cart-in-progress).

## How the figures are worked out

| Figure | How it's worked out |
| --- | --- |
| Which carts are listed | Every cart with at least 1 line in it across your accounts, as it stood at its last change. The date range doesn't apply. |
| Abandoned | Nobody has changed the cart for the number of days in **Abandoned after** or more, counted from its last change to today. A cart that was never changed after it was started counts from the day it was started. The rule starts at 3 days. |
| In progress | Any cart that isn't abandoned. |
| **Value in carts** | The total of every cart in your store's currency. Carts in other currencies aren't converted or added to it. |
| **Lines** and **Units** | The number of lines in the cart, and the quantities on them added up. |
| **Vs their usual** | The cart's value against the account's average order value. It shows a dash for a cart in another currency. |

**More detail**

When some carts are in another currency, such as euros from a second storefront, the **Value in carts** tile shows them beside the total, such as **+€1.4k**, or **+2 currencies** when there are several. Hover over it to see the amount and number of carts in each currency.

## FAQs

**Why doesn't the date range change the Carts page?**

Carts are shown as they stand today. A cart started months ago and still open is still worth chasing, so every open cart is listed whatever the date range.

**Why isn't a customer's cart listed?**

Only carts with at least 1 product in them are listed. An empty cart, or one that has been ordered, doesn't appear.

**Why isn't a cart in the Value in carts total?**

It's in another currency. Pulse doesn't convert currencies, so those carts are shown beside the total instead of in it.

**Can I search the carts?**

Not on this page. Sort or filter the table instead, or press ⌘K (Ctrl+K on Windows) anywhere in Pulse and type the account's name or the cart's reference. See [Search Pulse](https://docs.sparklayer.io/help/pulse/records.md#search-pulse).


---

# Quotes

URL: https://docs.sparklayer.io/help/pulse/quotes

Track your open quotes in Pulse: see how long each has waited, set its status, amend or delete it, chase the customer and convert it into an order.

> **Pulse is in early access.** Request it for your sales team. [Request early access](https://feedback.sparklayer.io/get-started?choice=now). [Try the interactive demo](https://www.sparklayer.io/pulse/).

> **Quick summary**
>
> - **Quotes** in Pulse is your quote pipeline: what's open, what it's worth, how old each quote is and which have gone stale.
> - Each quote has a status: **Open**, **Awaiting customer**, **Accepted** or **Declined**. Open and Awaiting customer quotes count as open. An open quote goes stale once it has been open 14 days or more.
> - From a quote you can change its status, amend its lines, delete it, send the customer a reminder, or convert it into an order. Changes you make are saved to the quote in the Quoting Engine, and the customer sees them.
> - Quotes come from the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md), included on Pro and Enterprise and an add-on on other plans.

A quote that nobody follows up is a lost order. **Quotes** lists every quote your accounts raised in the date range, largest first, with its age next to the day it was raised. You can see at a glance which customers are waiting on you, and which you're waiting on.

New to Pulse? Start with [Pulse](https://docs.sparklayer.io/help/pulse.md) for how to open it and how the date range works.

## The Quotes screen

4 tiles sum up your open quotes. The **Pipeline** table lists each quote.

| Part | What it shows / does |
| --- | --- |
| **Open quotes** tile | How many quotes are open: still awaiting a decision. |
| **On the table** tile | The total value of the open quotes. |
| **Oldest open** tile | The age in days of the oldest open quote, with its number and account. Click it to open that quote. |
| **Gone stale** tile | How many quotes have been open 14 days or more (**open 14+ days**). |
| **Pipeline** table | One row per quote, largest first: **Quote**, **Buyer**, **Raised**, **Age**, **Status**, **Lines** and **Value**. Accepted and declined quotes are greyed out. 20 quotes a page, with **Previous** and **Next**. Click a row to open the quote. |
| **Age** | Days since the quote was raised, such as **9d**. A stale quote shows **stale** in red, such as **16d · stale**. Hover over the age to see how it was counted. After you send a reminder, the date you chased it appears here. |
| **amended** | Shown next to a quote number when its lines have been changed since it was raised. |
| **Status** filter | Show quotes with one or more statuses. The menu shows how many quotes have each. |
| Search | Type a quote number or an account name (**Quote or buyer…**). |
| **Download CSV** | Saves every quote in the table, with your filter and search applied, as a CSV file. |

Click **Open quotes**, **On the table** or **Gone stale** to list the quotes behind it, largest first.

### Quote statuses

Each quote has 1 of 4 statuses:

| Status | Meaning |
| --- | --- |
| **Open** | No reply yet. |
| **Awaiting customer** | With the customer: you've done your part and you're waiting for them. |
| **Accepted** | Off the pipeline: the customer has said yes. |
| **Declined** | Kept for the record: the customer has said no. |

A status you set in Pulse is saved to the quote in the Quoting Engine, and the customer sees it. 

## Change a quote's status

1. In Pulse, click **Quotes** in the sidebar, then click the quote.
2. Click the status next to the quote number.
3. Choose **Open**, **Awaiting customer**, **Accepted** or **Declined**.

**More detail**

Accepted and Declined quotes leave the open totals and the **Gone stale** count. They stay in the **Pipeline** table, greyed out, so you keep a record. The change is added to the quote's timeline and saved to the quote in the Quoting Engine, so the customer sees the new status.

## Amend a quote

1. Open the quote and click **Amend** above its lines.
2. Change a quantity with the **−** and **+** buttons, or type a new one.
3. To take a product off the quote, click the bin icon on its line, or lower its quantity to 0.
4. Check the new total, shown next to the old one, then click **Save changes**.

**More detail**

You can amend open quotes only (**Open** or **Awaiting customer**). Amending changes quantities and removes lines: it can't change prices or add products. If you remove every line, saving asks you to confirm, then deletes the quote. Click **Cancel** to leave the quote as it was. Your changes are saved to the quote in the Quoting Engine, so the customer sees the new lines.

## Delete a quote

1. Open the quote and click **Delete quote**.
2. Click **Delete quote** again to confirm. The quote is deleted from the Quoting Engine too, so the customer no longer sees it. This can't be undone.

To keep a record of the quote, set its status to **Declined** instead of deleting it.

## Send the customer a reminder

1. Open the quote and click **Send reminder**. On a stale quote the button is highlighted.
2. Check Pulse's draft, which lists the quote's lines and total, and click **Copy**.
3. Paste it into an email to the customer and send it from your own mailbox.
4. Back in Pulse, click **Mark as sent**. Pulse adds a task to check the quote in 3 days, and the button then reads **Chase again**.

**More detail**

**Send reminder** is only shown on open quotes. Pulse doesn't send the email for you.  For what the draft contains and what **Mark as sent** records, see [Send a reminder](https://docs.sparklayer.io/help/pulse/records.md#send-a-reminder).

## Convert a quote into an order

1. Open the quote and click **Convert to order**. Pulse opens the order builder, signed in as the customer, with the quote's lines at the quoted prices.
2. Check the order and place it.

**More detail**

**Convert to order** is only shown on open quotes. Converting doesn't change the quote's status: set it to **Accepted** once the order is placed.  To start a separate order for the same account and leave the quote as it is, click **New order for** and the account's name instead: it opens an empty basket. See [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md).

## How the figures are worked out

| Figure | How it's worked out |
| --- | --- |
| Which quotes are listed | Quotes raised in the date range. Widen the date range to see older quotes. |
| Open | A quote with the status **Open** or **Awaiting customer**. |
| **Age** | The number of days from the day the quote was raised to today, whatever the date range. A quote raised today is 0 days old. |
| Stale | An open quote that has been open 14 days or more. Accepted and Declined quotes are never stale. |
| **Oldest open** | The open quote in the list with the highest age. |
| **On the table** | The total value of the open quotes in the list. |
| **Value** | The quantity times the unit price of each line, added up. |
| Lists behind the tiles | Every open quote, or every stale one, whatever the date range. They can list more quotes than the tile counts. |

Quotes are never counted as orders anywhere in Pulse. Each quote also opens in a panel with its lines, **Quote economics** and the account: see [A quote](https://docs.sparklayer.io/help/pulse/records.md#a-quote).

## FAQs

**When does a quote go stale?**

When it's still open (**Open** or **Awaiting customer**) and has been open 14 days or more. Its age shows **stale** in red, it counts towards **Gone stale**, and **Send reminder** is highlighted.

**Why can't I see an old quote?**

The list only shows quotes raised in the date range. Choose a longer range, such as **Last 24 months**, and clear the **Status** filter.

**Why is there no Amend, Send reminder or Convert to order button?**

They're only available on open quotes. Change the status back to **Open** first if the customer has changed their mind.

**Does converting a quote close it?**

No. **Convert to order** puts the quote's lines into an order, but the quote stays open. Set its status to **Accepted** once the order is placed, so it leaves your open totals.


---

# Receivables

URL: https://docs.sparklayer.io/help/pulse/receivables

See which of your accounts owe money in Pulse, how overdue each invoice is, and record payments, promises and disputes or chase the customer.

> **Pulse is in early access.** Request it for your sales team. [Request early access](https://feedback.sparklayer.io/get-started?choice=now). [Try the interactive demo](https://www.sparklayer.io/pulse/).

> **Quick summary**
>
> - **Receivables** in Pulse shows what your accounts owe: the total outstanding, how much is overdue and how old it is, and a list of every unpaid invoice.
> - An invoice is overdue from the day after its due date: the invoice date plus the account's payment terms, such as Net 30.
> - Receivables lists Shopify orders with no payment against them, and invoices from SparkLayer's [Xero](https://docs.sparklayer.io/help/integrations/accountancy/xero.md) and [QuickBooks Online](https://docs.sparklayer.io/help/integrations/accountancy/quickbooks.md) integrations. Your accounting system stays the ledger: a status you set in Pulse is a note for you and doesn't change it.
> - Open an invoice to **Mark as paid**, record a **Payment promised** or **Disputed** invoice, send a reminder or add a task to chase it.

Know who owes money before you call a customer. **Receivables** lists every unpaid invoice for your accounts, most overdue first. Chase what's late, and avoid pitching new orders to an account with bills outstanding.

New to Pulse? Start with [Pulse](https://docs.sparklayer.io/help/pulse.md) for how to open it and how the date range works.

## The Receivables screen

4 tiles and an ageing bar sum up what's owed. The **Who owes what** table lists each invoice.

| Part | What it shows / does |
| --- | --- |
| **Outstanding** tile | The total of all unpaid invoices, and how many there are. |
| **Overdue** tile | The total of unpaid invoices past their due date, and how many are past terms. |
| **Oldest overdue** tile | How many days the most overdue invoice is past its due date, with its account and invoice number. Click it to open that invoice. With nothing overdue, it reads **nothing past terms**. |
| **Within terms** tile | The total of unpaid invoices that aren't due yet. |
| **Ageing** | A bar splitting the outstanding total into **Current** (not yet due), **1–30d over** and **30d+ over**, with the amount in each. **Source** shows when payment status last synced. |
| **Who owes what** table | One row per invoice: **Buyer**, **Invoice**, **Dated**, **Due**, **Status** and **Value**. Unpaid invoices come first, most overdue first, then largest first. 20 invoices a page, with **Previous** and **Next**. Click a row to open the invoice. |
| **Invoice** | The invoice number from your accounting system, or, for a Shopify order with no payment against it, its order number followed by **· order**. |
| **Show paid** | Adds paid invoices to the table, greyed out, with a count next to it. While paid invoices are showing, the button reads **Hiding nothing**: click it again to hide them. |
| Search | Type an account name or an invoice number (**Buyer or invoice…**). |
| **Download CSV** | Saves every invoice in the table, with your search applied, as a CSV file, including the days overdue. |

Click **Outstanding**, **Overdue** or **Within terms** to list the invoices behind it, most overdue first.

### Invoice statuses

The **Status** column shows where each invoice stands:

| Status | Meaning |
| --- | --- |
| **Within terms** | Unpaid, and not yet past its due date. |
| **12d overdue** (for example) | Unpaid and past its due date by that many days. Amber up to 30 days, red after that. |
| **Payment promised** | You've recorded that the customer has promised a payment date. |
| **Disputed** | You've recorded that the customer is querying the invoice. |
| **Paid** | Paid in your accounting system. **Paid · marked** means you marked it paid in Pulse. |

When you change a status yourself, you choose from:

| Option | Use it when |
| --- | --- |
| **Paid** | Payment received. |
| **Payment promised** | A date is promised. |
| **Disputed** | The invoice is being queried. |
| **Outstanding** | You want to set the invoice back to open, for example to undo a status you set by mistake. |

## Mark an invoice as paid

1. In Pulse, click **Receivables** in the sidebar, then click the invoice.
2. Click **Mark as paid**.

**More detail**

The invoice leaves the outstanding and overdue totals straight away and shows **Marked Paid by you on** today's date. Your accounting system isn't updated: when the payment is recorded there, the synced status takes over. To see the invoice again, click **Show paid**.

## Record a promised payment or a dispute

1. Open the invoice.
2. Click the status next to the invoice number.
3. Choose **Payment promised** or **Disputed**.

The menu reminds you that the status is **Recorded here only** and that your accounting system isn't updated. Promised and disputed invoices still count towards **Outstanding** and, once past their due date, **Overdue** and the ageing bar.

## Chase an invoice

1. Open the invoice and click **Send reminder**. On an overdue invoice the button is highlighted.
2. Check Pulse's draft, which gives the amount, due date and terms, and how many days overdue it is, and click **Copy**.
3. Paste it into an email to the customer and send it from your own mailbox.
4. Back in Pulse, click **Mark as sent**. Pulse adds a task to check the invoice in 3 days, and the button then reads **Chase again**.

**More detail**

**Send reminder** is only shown on unpaid invoices. Pulse doesn't send the email for you.  For what the draft contains and what **Mark as sent** records, see [Send a reminder](https://docs.sparklayer.io/help/pulse/records.md#send-a-reminder).

To chase it later instead, open the invoice and click **Add a task**. Pulse adds a task for today to your [Task List](https://docs.sparklayer.io/help/pulse/task-list.md), such as "Chase invoice INV-1001 — $540, 12d overdue".

## See what an invoice is for

1. Open the invoice.
2. Under **What it's for**, check the order and its lines. Click **Open order** to open the order itself.

An invoice that rolls up an account's balance rather than one order shows **Statement invoice** and the date the balance was carried. When only part of an order is unpaid, the panel shows the order total and the unpaid balance. To see the whole account, click **Open buyer**. The invoice panel is described in [An invoice](https://docs.sparklayer.io/help/pulse/records.md#an-invoice).

## How the figures are worked out

| Figure | How it's worked out |
| --- | --- |
| Which invoices are listed | Invoices from SparkLayer's Xero and QuickBooks Online integrations, and Shopify orders with no payment against them, dated in the date range. Widen the date range to see older invoices. What's owed on them is always as of today. |
| Due date | The invoice date plus the account's payment terms. Pulse takes the first number in the terms as the days, so Net 30 is 30 days and Net 45–60 is 45. An account with no number in its terms gets 30 days. |
| Overdue | An unpaid invoice whose due date has passed. Days overdue are counted from the due date to today, so an invoice due today is still within terms and is 1 day overdue tomorrow. |
| Unpaid | Any status except **Paid**: **Within terms**, overdue, **Payment promised** and **Disputed**. |
| **Outstanding** | The total of every unpaid invoice, including promised and disputed invoices. |
| **Within terms** | **Outstanding** minus **Overdue**. |
| **Ageing** | The outstanding total split by how far past the due date each invoice is: not yet due, 1 to 30 days, or more than 30 days. |
| Lists behind the tiles | Every unpaid invoice that fits the tile, whatever the date range. They can list more invoices than the tile counts. |

Payment status is synced from your accounting system on a schedule. The note under the table shows when it last synced.

## FAQs

**When does an invoice become overdue?**

The day after its due date. The due date is the invoice date plus the account's payment terms, so an invoice dated 1 March on Net 30 terms is due on 31 March and 1 day overdue on 1 April.

**I marked an invoice paid by mistake. How do I undo it?**

Click **Show paid**, open the invoice, click its status and choose **Outstanding**.

**Why doesn't the total match my accounting system?**

Receivables only lists invoices dated in the date range, and it leaves out invoices you've marked paid. Choose a longer date range, and check whether you've marked any invoices paid that aren't paid yet in your accounting system. The status also only updates when your accounting system next syncs.

**Does the customer see the status I set?**

No. Statuses you set in Pulse are for you and your team, and aren't sent to the customer or your accounting system.


---

# Products

URL: https://docs.sparklayer.io/help/pulse/products

See what your accounts buy in Pulse, by product range and variant, and find who buys each product and who doesn't stock it yet.

> **Pulse is in early access.** Request it for your sales team. [Request early access](https://feedback.sparklayer.io/get-started?choice=now). [Try the interactive demo](https://www.sparklayer.io/pulse/).

> **Quick summary**
>
> - **Products** in Pulse shows what your accounts buy, by range: a range is a product with all its variants, such as sizes or colours.
> - The tiles and chart follow the date range. The **What's selling** table and each product's panel cover every order on record.
> - Open a range or a variant to see how it has sold over 24 months, **Who takes it** and who's **Not stocking it yet**: the accounts to offer it to next.
> - From a product you can add it to a customer's order or click **View product** to open it on your storefront.

Use **Products** to see which ranges carry your book and to find your next conversation: a product most of your accounts buy is an easy one to suggest to the accounts that don't.

New to Pulse? Start with [Pulse](https://docs.sparklayer.io/help/pulse.md) for how to open it and how the date range works.

## The Products screen

The tiles and chart show what's selling in the date range. The **What's selling** table lists every range your accounts have ordered.

| Part | What it shows / does |
| --- | --- |
| **Ranges** tile | How many product ranges your accounts have ever ordered, and how many variants they include. |
| **Units** tile | The number of units ordered in the date range. |
| **Revenue** tile | The value of those units. Click it to list the orders behind it. |
| **Top range** tile | The range with the most revenue in the date range, and its revenue. |
| **Units by range** | A stacked bar chart of units ordered in each period of the date range, one colour per range, for your 8 best-selling ranges. Choose the **Period** (**Auto**, **Day**, **Week** or **Month**). Click a bar to see its units by range and the orders in it, or a range name under the chart to open that range. |
| Month comparison strip | Under the chart: units of those ranges this month so far, then 1, 3 and 6 months ago, each with a percentage change. |
| **What's selling** table | One row per range, highest revenue first: **Range**, **SKU**, **Units**, **Orders**, **Buyers**, **Revenue** and **Last ordered**. 20 ranges a page, with **Previous** and **Next**. Click a row to open the range. |
| Arrow next to a range | **Show variants** lists the range's variants underneath it, each with the same columns. Click again to **Hide variants**. |
| **SKU** | The SKU of a range with one variant, or the number of SKUs in it, such as **4 SKUs**. |
| **Buyers** | How many of your accounts have ordered the range, such as **3 of 6**. |
| Search | Type a range, product name or SKU (**Range, product or SKU…**). Ranges with a matching variant open to show it. |
| **Download CSV** | Saves every range in the table, with your search applied, as a CSV file. |

## See who buys a product, and who doesn't

1. In Pulse, click **Products** in the sidebar.
2. Click a range, or click the arrow and then a variant.
3. Under **Who takes it**, check each account that orders it, with their units, when they last ordered it and their revenue.
4. Under **Not stocking it yet**, check the accounts that have never ordered it. Click an account to open it.

**More detail**

Each account under **Not stocking it yet** shows its health, when it last ordered anything and what its orders are usually worth, so you can pick the best one to call first. The panel also shows **Units**, **Revenue** and **On orders** for all time, **Buyers** with how many aren't stocking it yet, and a **Movement · 24 months** chart. A range's panel lists its **Variants**, and a variant's panel links back to its range. See [A product](https://docs.sparklayer.io/help/pulse/records.md#a-product).

## Add a product to a customer's order

1. Open the range or variant.
2. Click **Add to a buyer's cart**.
3. Under **Add to whose cart?**, search for the account and choose it. Pulse opens the order builder, signed in as the customer, with the product added.
4. Check the order and place it.

In the **Add to whose cart?** list, **stocks it** means the account has ordered the product before, and **new line** means it hasn't. See [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md) for how the order builder works.

**More detail**

From a variant, Pulse adds that variant. From a range, it adds the variants the account usually orders, or the range's best-selling variant if they don't order any. The quantity is the account's usual quantity when the product is in their usual basket. Otherwise it's the median quantity of that product on your accounts' orders, or 12 if nobody has ordered it yet.

## View a product on your storefront

1. Open the range or variant.
2. Click **View product**. The product page opens in a new tab. 

## How the figures are worked out

| Figure | How it's worked out |
| --- | --- |
| **Units** and **Revenue** tiles, **Units by range** | Lines on orders placed in the date range. Revenue is quantity times the unit price the account paid. |
| **Top range** | The range with the most revenue in the date range. |
| Best-selling ranges in the chart | The 8 ranges with the most revenue across every order on record. |
| **What's selling** table | Every order on record, whatever the date range: units, order lines, the accounts that have ordered the range, revenue and the last order date. |
| **Orders** | The number of order lines for the range or variant. An order with 2 variants of a range counts twice for the range. |
| **Buyers** | Accounts that have ordered the range or variant at least once, out of all your accounts. |
| **Not stocking it yet** | Your accounts that have never ordered the range or variant. Accounts you've invited that haven't started ordering aren't listed. |
| Range | A product and all its variants. |

Products only counts orders placed through your storefront. See [Where the figures come from](https://docs.sparklayer.io/help/pulse.md#where-the-figures-come-from).

## FAQs

**Why don't the What's selling figures match the tiles?**

The tiles and the **Units by range** chart follow the date range. The **What's selling** table and each product's panel count every order on record, whatever the date range.

**How much does Add to a buyer's cart add?**

The account's usual quantity, when the product is in their usual basket. Otherwise Pulse uses the median quantity of that product on your accounts' orders, or 12 if nobody has ordered it yet. You can change the quantity in the order builder before placing the order.

**Why isn't an account listed under Not stocking it yet?**

Either it has ordered the product at least once, in which case it's under **Who takes it**, or it's an account you've invited that hasn't started ordering yet.


---

# Customers

URL: https://docs.sparklayer.io/help/pulse/customers

Manage your book in Pulse: check each account's health score and segment, filter by health band, invite accounts and buyers, and review trade applications.

> **Pulse is in early access.** Request it for your sales team. [Request early access](https://feedback.sparklayer.io/get-started?choice=now). [Try the interactive demo](https://www.sparklayer.io/pulse/).

> **Quick summary**
>
> - **Customers** in Pulse lists every account you look after and how healthy each one is. It has 4 tabs: **Accounts**, **Buyers**, **Customer groups** and **Applications**.
> - The **Account health** card scores every account out of 100 and sorts them into bands: **Healthy** (75 to 100), **Stable** (50 to 74), **At risk** (30 to 49) and **Critical** (0 to 29). Click a band to see those accounts.
> - Add an account with **Add account**, invite a person to order for an existing account with **Invite a buyer**, and approve new accounts from the **Applications** tab.

Use **Customers** to find the accounts that need a call before they drift away, and to bring new accounts and buyers into your book.

New to Pulse? Start with [Pulse](https://docs.sparklayer.io/help/pulse.md) for how to open it and how the date range works.

## Accounts, buyers and customer groups

Pulse uses 3 words for 3 different things:

| Term | What it is | Example |
| --- | --- | --- |
| **Account** | A company you sell to. Orders, quotes, invoices and health belong to the account. | A garden centre |
| **Buyer** | A person who orders for an account. An account can have several. | The garden centre's purchasing manager |
| **Customer group** | The price lists and terms that a set of accounts share. Each account is in one group. | Your Trade group |

Customer groups are set up at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app, not in Pulse: see [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md). A buyer is a [company user](https://docs.sparklayer.io/help/customers/company-users.md) on the account.

## The Customers screen

The 4 tiles at the top are **Active buyers** (accounts that ordered), **Orders**, **GMV** and **Avg order value**. They're the same as on [Orders](https://docs.sparklayer.io/help/pulse/orders.md#how-the-figures-are-worked-out), and follow the date range. Click a tile to see what makes it up. Below the tiles are the tabs. The **Applications** tab shows how many applications are still open, and so does the **Customers** badge in the sidebar.

### Accounts tab

| Part | What it shows / does |
| --- | --- |
| **Account health** card | How many accounts are scored, how much lifetime spend sits with **At risk** and **Critical** accounts, and a bar showing how many accounts are in each band and their share. Click a band in the bar to show only those accounts in the table. Click it again, or **Show all**, to show every account. |
| **Accounts** table | One row per account: **Account**, **Health**, **Segment**, **Group**, **Agent**, **Orders**, **Lifetime spend**, **Last order** and **Came via**. Click a row to open the account. The table covers each account's whole history: the date range doesn't change it. |
| **Account** | The company name, with its website and payment terms underneath. |
| **Health** | The account's score out of 100 and its band. Hover over it to see how the score was worked out. An account that hasn't ordered yet shows **Invited** instead. |
| **Segment** | Where the account is in its life with you (see [Segments](#segments)). Hover over it to see why. An account that hasn't ordered yet shows **no orders yet**. |
| **Group** and **Agent** | The account's customer group and the sales agent who looks after it. |
| **Last order** | How long ago the account last ordered and, if it has a regular rhythm, how often it usually orders (for example, **every \~21d**). |
| **Came via** | How the account joined: **ERP sync**, **Application**, **Added by you** or **Invited**. |
| Column headings | Click **Account**, **Health**, **Orders**, **Lifetime spend** or **Last order** to sort by it. **Account** sorts A to Z first and the others highest first. Click again to reverse the order. The table starts sorted by **Lifetime spend**, highest first. |
| **Segment** filter | Show one or more segments. Each shows how many accounts are in it. |
| **Health** filter | Show one band, or **All**. Each band shows its colour and how many accounts are in it. Picking a band hides accounts that haven't ordered yet. |
| Search | Type an account name, email or account number (**Search accounts…**). |
| **Add account** | A menu of the 3 ways an account joins your book (see [Add an account](#add-an-account)). |
| **Download CSV** | Saves every account the filters show, with its health score, segment and usual gap between orders. |

The table shows 20 accounts a page. If no accounts match your filters, click **Clear filters**: it clears the **Segment** and **Health** filters and the search.

### Buyers tab

| Part | What it shows / does |
| --- | --- |
| **Buyers** table | One row per person: **Name**, **Account**, **Email**, **Role**, **Since** and **Status** (**Active**, or **Invited** until they accept). Each account's main contact is listed as **Primary buyer**. Click the account to open it. |
| **Invite a buyer** | Invites a new person to order for one of your accounts. See [Invite a buyer](#invite-a-buyer). |
| **Download CSV** | Saves the list of buyers. |

### Customer groups tab

| Part | What it shows / does |
| --- | --- |
| **Customer groups** table | One row per group: **Group**, **Price lists**, **Who it's for**, **Accounts**, **Orders** and **GMV**. Orders and GMV follow the date range. Click an account to open it. |
| **Pricing** | Opens [Pricing](https://docs.sparklayer.io/help/pulse/pricing.md), which compares how each group performs. |
| **Download CSV** | Saves the table, with a count of accounts in each group. |

### Applications tab

| Part | What it shows / does |
| --- | --- |
| **Trade applications** | Every application from your storefront's application form, newest first, with how many are still to contact. Each shows the company, its status (**New**, **In review**, **Approved** or **Declined**), the contact, their trade and when they applied. With none, it says **No applications yet.** |
| **Contact** | Adds a task to your [Task List](https://docs.sparklayer.io/help/pulse/task-list.md) to call the applicant today, and moves a **New** application to **In review**. |
| **Review** | Opens the application, where you can approve or decline it. |

Applications come from a trade application form on your storefront: see [Forms](https://docs.sparklayer.io/help/forms.md). 

## Find the accounts that need attention

1. In Pulse, click **Customers** in the sidebar. The **Accounts** tab opens.
2. In the **Account health** card, click **At risk** or **Critical**. The table shows only those accounts.
3. Hover over an account's health score to see which part of the score is low.
4. Click the account to open it, then call them, plan a visit or start an order.

**More detail**

You can also choose a band from the **Health** filter, and combine it with the **Segment** filter and the search box: the card, the filter counts and the table always count the same accounts. Click **Show all** to clear the band. For the account panel, see [An account](https://docs.sparklayer.io/help/pulse/records.md#an-account); for accounts that are late with a reorder, see [Reorder radar](https://docs.sparklayer.io/help/pulse/reorder-radar.md).

## Add an account

1. On the **Accounts** tab, click **Add account**.
2. Choose how the account joins your book:
   - **Invite an account**: add the company and its first buyer yourself.
   - **Review applications**: go to the **Applications** tab to approve an account that applied through your storefront. The menu shows how many are open.
   - **ERP sync**: nothing to do. It's marked **automatic**: accounts synced from your other systems appear on their own, and the menu shows where they sync from and when they last synced. 
3. For **Invite an account**, the **Add a buyer** form opens. Enter the buyer's **First name**, **Last name** and **Email**, and the **Company** name, then click **Add buyer**.

**More detail**

All 4 fields are needed. The buyer gets the same invite email as a customer you add in Sales Agent mode, and the account appears in your book straight away with **Came via** set to **Invited**. If they already have an account on your store, they can sign in with it. It has no health score until it orders. See [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md).

## Invite a buyer

1. Click the **Buyers** tab, then **Invite a buyer**.
2. Choose the **Account** they'll order for.
3. Enter their **First name**, **Last name** and **Email**.
4. Choose their **Role**: **Buyer** (the default), **Primary buyer**, **Finance contact** or **Store manager**.
5. Click **Send invite**.

They get an invite to sign in and order for that account, and show on the **Buyers** tab as **Invited** until they accept. You can also invite a buyer from an account: on its **Overview** tab, click **Invite a buyer** in the **Buyers** card, and the account is chosen for you.

The 4 roles map to the roles company users have: see [Roles](https://docs.sparklayer.io/help/customers/company-users.md#roles).

## Review a trade application

1. Click the **Applications** tab.
2. To follow up first, click **Contact**: Pulse adds a task to call the applicant today.
3. Click **Review** to open the application, with the applicant's answers and how the ranges they asked about sell.
4. Click **Approve & invite** to create the account and email the contact an invite, or **Decline**.

**More detail**

To show you're working on an application, click **Mark in review**. A declined application can be reopened with **Reopen**. Once approved, the account opens, and appears on the **Accounts** tab with **Came via** set to **Application**. The application panel is described in [A trade application](https://docs.sparklayer.io/help/pulse/records.md#a-trade-application).

## How account health is scored

Each account is scored out of 100 on its own order history, from 3 parts:

| Part | Points | How it's scored |
| --- | --- | --- |
| **Cadence** | Up to 40 | How long it's been since the last order, against the account's usual gap between orders. Full points while they're within their usual gap, falling evenly to none once it's been 2.5 times their usual gap. An account without a regular rhythm yet is scored on days since its last order (see below). |
| **Spend trend** | Up to 30 | Spend in the last 90 days against the 90 days before. 30 if it's up by 10% or more, 23 if it's within 10% either way, 12 if it's down by more than 10%, 4 if they've spent nothing in the last 90 days, and 0 with no spend in 180 days. |
| **Engagement** | Up to 30 | How many orders the account has placed: 30 for 20 or more, 24 for 8 to 19, 16 for 3 to 7, 10 for 2 and 4 for 1. |

An account without a regular rhythm scores **Cadence** on days since its last order:

| Days since last order | Points |
| --- | --- |
| Up to 30 | 40 |
| 31 to 60 | 34 |
| 61 to 90 | 26 |
| 91 to 180 | 16 |
| 181 to 365 | 8 |
| More than 365 | 0 |

The total puts the account in a band:

| Band | Score |
| --- | --- |
| **Healthy** | 75 to 100 |
| **Stable** | 50 to 74 |
| **At risk** | 30 to 49 |
| **Critical** | 0 to 29 |

An account's usual gap is the average number of days between its orders, worked out once it has orders on at least 3 separate days. See [how the usual gap is worked out](https://docs.sparklayer.io/help/pulse/reorder-radar.md#how-the-figures-are-worked-out). Accounts that have been invited but haven't ordered yet aren't scored. Health only uses orders placed through your storefront: see [Where the figures come from](https://docs.sparklayer.io/help/pulse.md#where-the-figures-come-from).

On an account's **Overview** tab, the **Health** card shows the score, the part that's holding it back most, and **How it's calculated** for the full working.

## Segments

An account's segment shows where it is in its life with you, using the same fixed day counts for every account. Pulse checks the rules in this order, and the first that fits is the segment:

| Segment | Means |
| --- | --- |
| **New** | Became a customer in the last 90 days, counted from its **Customer since** date. Accounts that haven't ordered yet are **New** too. |
| **Dormant** | No orders for more than 90 days. |
| **One-off** | A single order, placed in the last 90 days, by an account that's been a customer for longer than that. |
| **At risk** | Repeat orders, but last ordered between 61 and 90 days ago. |
| **Champions** | 8 or more orders, and ordered in the last 60 days. |
| **Loyal** | 2 to 7 orders, and ordered in the last 60 days. |

## FAQs

**Why is an account's health different from its segment?**

They measure different things. Health compares the account with its own rhythm and spend, so a customer who always orders every few months can be **Healthy**. Segments use the same fixed day counts for every account.

**Why don't the band counts add up to all my accounts?**

Invited accounts with no orders have no score, so they're in no band. The card also counts only the accounts left by the **Segment** filter and the search box.

**Why does the New segment include accounts that haven't ordered?**

An account is **New** for its first 90 days as a customer, whether or not it has ordered. Accounts you've invited count from the day you invited them, so they show in the **New** count until they're 90 days old.

**Can I move an account to another customer group from Pulse?**

No. Customer groups are managed at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app: see [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md). [Pricing](https://docs.sparklayer.io/help/pulse/pricing.md) shows accounts that might belong in a different group.


---

# Pricing

URL: https://docs.sparklayer.io/help/pulse/pricing

Compare how each customer group performs in Pulse: orders, spend, reorder rate and spend per account, plus accounts that might belong in a better group.

> **Pulse is in early access.** Request it for your sales team. [Request early access](https://feedback.sparklayer.io/get-started?choice=now). [Try the interactive demo](https://www.sparklayer.io/pulse/).

> **Quick summary**
>
> - **Pricing** in Pulse compares your customer groups: how many accounts each has, what they order, how often they come back and what each account spends.
> - **Worth a better group** lists established accounts whose average order is bigger than their group suggests.
> - It's read-only. Customer groups and their price lists are managed at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app, not in Pulse.

Every account is in one [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md), which decides the price lists it orders from. **Pricing** shows how each group performs, using what accounts actually paid, so you can see which groups are worth growing and which accounts have outgrown theirs.

New to Pulse? Start with [Pulse](https://docs.sparklayer.io/help/pulse.md) for how to open it and how the date range works.

## The Pricing screen

| Part | What it shows / does |
| --- | --- |
| **Customer groups** tile | How many customer groups there are, how many of them have ordered in the date range, and the biggest group's share of GMV (with more than 3 groups, the top 3's share). |
| **Biggest group** tile | The group with the most GMV in the date range, and its GMV. |
| **Best spend per account** tile | The highest spend per active account of any group, and which group it is. |
| **Worth a better group** tile | How many established accounts are outsizing their group. |
| **How each customer group performs** table | One row per group, the most GMV first: **Group**, **Price lists**, **Accounts**, **Orders**, **GMV**, **AOV**, **Reorder %** and **Spend / account**. A group with no orders in the date range shows **—** for the figures that need them. Click an account to open it. |
| **Worth a better group** list | Each account that might belong in a better group, the biggest average order first: **Account**, **Group**, **Orders**, **AOV**, and **Why**, which names the group it compares with. When there are none, it says **Nobody is out of place — every established account orders in line with its group.** |
| **Download CSV** | On each table. Saves the rows shown. The **Worth a better group** file adds the group each account compares with and that group's lowest average order. |

The note under the table explains why Pulse shows no discount percentages. A group can carry a percentage off, a manual price list or several layered together, with overrides for single accounts on top. So Pulse measures what each account actually paid.

## Compare your customer groups

1. In Pulse, click **Pricing** in the sidebar.
2. Set the date range for the period you want to compare.
3. In **How each customer group performs**, compare **Reorder %** and **Spend / account** across the groups.

**More detail**

A group with a high **Spend / account** but a low **Reorder %** relies on a few big orders; a high **Reorder %** means its accounts keep coming back. To see the price lists behind a group, or to change them, 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, or ask whoever manages pricing.

## Find accounts that might belong in a better group

1. Look at the **Worth a better group** list at the bottom of the page.
2. Read **Why** for each account: it names the next group up and the average order the account beats, for example **Beats the smallest Gold account's average ($420)**.
3. Click the account to open it and check its history before you suggest a change.

To move an account to another group, see [Add a customer to a group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group). On Shopify, if the account is a company, change the company's **Customer group** at **Companies** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/companies)), or **SparkLayer Wholesale > Companies** in the Shopify app instead: see [Companies](https://docs.sparklayer.io/help/customers/companies.md). 

## How the figures are worked out

The group table follows the date range. The account counts don't, and nor do the order counts and averages in **Worth a better group**, which cover each account's whole history.

| Figure | How it's worked out |
| --- | --- |
| **Accounts** | Every account in the group. |
| **Orders** and **GMV** | Orders placed by the group's accounts in the date range, and their total value. |
| **AOV** | Average order value: GMV divided by orders. |
| **Reorder %** | Of the group's accounts that ordered in the date range, the share that ordered at least twice in it. |
| **Spend / account** | GMV divided by the number of the group's accounts that ordered in the date range. |
| **Worth a better group** | An account with at least 3 orders whose average order is bigger than the smallest average order among established accounts (3 or more orders) in any group with a higher **Spend / account** than its own. It's worked out from what accounts paid, not from price lists. |

Pricing only counts orders placed through your storefront. See [Where the figures come from](https://docs.sparklayer.io/help/pulse.md#where-the-figures-come-from).

## FAQs

**Why doesn't Pricing show each group's discount?**

A group's prices can come from a percentage off, a manual price list or several layered together, with overrides for single accounts. So Pulse shows what accounts actually paid instead of a configured discount.

**Why is an account in Worth a better group when it hardly ordered this period?**

The list uses each account's lifetime orders and average order, so an account that has ordered at least 3 times can appear even if it was quiet in the date range. Only the comparison between groups, by **Spend / account**, follows the date range.

**Why does a group show — for Reorder % and Spend / account?**

None of its accounts ordered in the date range. Widen the date range to compare it with the other groups.


---

# Reorder radar

URL: https://docs.sparklayer.io/help/pulse/reorder-radar

Track how often each account orders in Pulse, see who is due, overdue or has gone quiet, and turn them into reorder calls on your Task List.

> **Pulse is in early access.** Request it for your sales team. [Request early access](https://feedback.sparklayer.io/get-started?choice=now). [Try the interactive demo](https://www.sparklayer.io/pulse/).

> **Quick summary**
>
> - **Reorder radar** in Pulse tracks every account's order rhythm: how often they order, when they last did, when they're next due and what their usual order is worth.
> - Each account gets a status, such as **On rhythm**, **Due**, **Overdue** or **Gone quiet**, worked out from its own history rather than a fixed number of days.
> - **Action plan** turns the due, overdue and quiet accounts into reorder calls for today on your [Task List](https://docs.sparklayer.io/help/pulse/task-list.md).

Most B2B customers reorder on a rhythm: one every couple of weeks, another every quarter. **Reorder radar** learns each account's rhythm from its orders and tells you who should have ordered by now, so you can call before a late reorder becomes a lost customer.

New to Pulse? Start with [Pulse](https://docs.sparklayer.io/help/pulse.md) for how to open it.

## The Reorder radar screen

| Part | What it shows / does |
| --- | --- |
| **On rhythm** tile | How many accounts are inside their usual gap between orders. |
| **Due or overdue** tile | How many accounts are due or overdue, and how many of those are past their date. |
| **Gone quiet** tile | How many accounts are well past their rhythm. |
| **Worth chasing** tile | The total value of the usual baskets of every due, overdue and quiet account: roughly what those calls could bring in. |
| **Order frequency** table | One row per account that has ordered, the most urgent first: **Status**, **Account**, **Frequency**, **Gaps**, **Last order**, **Next due** and **Usual basket**. Click an account's name to open it. |
| **Frequency** | How often the account orders, such as **every \~21d**, with orders per month and how many orders it placed in the last 90 days. A newer account shows **one order so far** or **no pattern yet**. |
| **Gaps** | A small line of the days between the account's recent orders, up to its last 9 orders. A flat line is a steady customer; spikes are orders that came late. Hover over it for details. It needs at least 3 orders. |
| **Next due** | The date the next order is expected, with how many days away it is, or how many days ago it was due. **Today** if it's due today. |
| **Usual basket** | What the account's next order is likely to be worth. |
| **Prep** | Opens the account's call prep sheet: its key facts and what to talk about. |
| **Order** | Opens the order builder, signed in as the customer, with their usual basket ready to check and place. |
| **Action plan** | Turns the due, overdue and quiet accounts into tasks (see [Plan your reorder calls](#plan-your-reorder-calls)). |
| **Download CSV** | Saves every row, with the usual gap, orders in the last 90 days and how many days until each account is due. |

Click **On rhythm**, **Due or overdue** or **Gone quiet** to list the accounts behind it. **Worth chasing** lists the due and overdue accounts. The table shows 20 accounts a page, and has no search or filters: the order of the rows does the sorting for you.

### Order frequency statuses

Each account's status comes from its own rhythm. The table lists them in this order, and within a status, the account due soonest (or most overdue) comes first.

| Status | Means |
| --- | --- |
| **Overdue** | More than 3 days past the date their next order was due. |
| **Gone quiet** | At least 2.5 times their usual gap since their last order, and more than 30 days. The status shows how many days, such as **Gone quiet · 75d**. An account that has gone quiet shows as **Gone quiet**, not **Overdue**. |
| **Due** | Their next order is due today, or was due up to 3 days ago. |
| **On rhythm** | Their next order isn't due yet. |
| **Irregular** | No rhythm yet: 2 orders, or a single order placed more than 90 days ago. |
| **New** | 1 order so far, placed in the last 90 days. |

Accounts that haven't ordered yet aren't listed.

## Plan your reorder calls

1. In Pulse, click **Reorder radar** in the sidebar.
2. Click **Action plan**. The **Reorder action plan** lists every due, overdue and quiet account, each ticked.
3. Untick any account you don't want to call.
4. Click **Add to Task List**. Pulse adds a task for each ticked account and opens your open tasks on the Task List.

**More detail**

Each task is dated today and worded from the account's own rhythm, for example "Reorder call · 6d overdue · usual basket \~$800", "Reorder call · due today · usual basket \~$800" or "Reorder call · quiet 75 days". The foot of the plan shows how many tasks you're adding and roughly what their usual baskets are worth, and **Add to Task List** is greyed out while nothing is ticked. If nobody is due, it says **Nobody is due — nothing to plan.** See [Task List](https://docs.sparklayer.io/help/pulse/task-list.md).

## Call or order for a due account

1. Find the account in the **Order frequency** table. Overdue and due accounts are near the top.
2. Click **Prep** to see the account's facts and talking points before you call.
3. Click **Order** to build their usual order, signed in as the customer, then check it with them and place it.

**More detail**

The order builder opens with the account's usual basket: the products and quantities they normally order, at their prices. Change anything before you place it. See [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md). See also [the prep sheet](https://docs.sparklayer.io/help/pulse/records.md#prepare-for-a-call-or-visit) and [the account panel](https://docs.sparklayer.io/help/pulse/records.md#an-account).

## How the figures are worked out

| Figure | How it's worked out |
| --- | --- |
| Usual gap | The average number of days between the account's own orders. Pulse only works one out once the account has orders on at least 3 separate days, so it never guesses a rhythm. Several orders on the same day count as one, and cancelled orders and quotes don't count. It looks at the last 12 months first. If the account hasn't ordered on 3 separate days in that time, it uses the account's full history. |
| **Next due** | The date of the last order plus the usual gap. |
| **Usual basket** | The products on at least half of the account's orders, each at its usual (median) quantity and the account's own price. It predicts the next order, so it can differ from the average order value. If no product is on half their orders, it's their average order value. |
| **Frequency** | Orders per month is 30 divided by the usual gap. |
| **Gaps** | The days between each of the account's last 9 orders. |
| **Worth chasing** | The usual baskets of the due, overdue and quiet accounts, added up. |

Reorder radar always reads as of today: the date range at the top of Pulse doesn't change it. Reorder radar only uses orders placed through your storefront, so an account that also orders by phone, by email or through your ERP can look late when it isn't. See [Where the figures come from](https://docs.sparklayer.io/help/pulse.md#where-the-figures-come-from).

## FAQs

**Why is an account shown as overdue when it ordered recently?**

The order may not have been placed through your storefront. Orders taken by phone or email, or keyed into your ERP, aren't counted, so Pulse doesn't know about them.

**Why does an account show no rhythm?**

Pulse needs orders on at least 3 separate days to work out how often an account orders. Several orders on the same day count as one, and cancelled orders and quotes don't count. It looks at the last 12 months first, and uses the account's full history if there aren't 3 order days in that time. Until then, the account shows **New** or **Irregular**, and isn't included in the action plan. See [How the figures are worked out](#how-the-figures-are-worked-out).

**Why isn't a new account on Reorder radar?**

Accounts that haven't ordered yet, such as accounts you've invited, aren't listed. They appear after their first order, as **New**.

**Can I date reorder calls for later?**

No. The action plan dates every task today, because every account in it is due now, overdue or quiet. To plan a call for another day, open the account and add a task with a **Due** date on its **Tasks & Notes** tab instead.


---

# Retention

URL: https://docs.sparklayer.io/help/pulse/retention

See whether your accounts keep ordering in Pulse: repeat rate, how many are active, and cohorts grouped by the quarter each account first ordered.

> **Pulse is in early access.** Request it for your sales team. [Request early access](https://feedback.sparklayer.io/get-started?choice=now). [Try the interactive demo](https://www.sparklayer.io/pulse/).

> **Quick summary**
>
> - **Retention** in Pulse answers "do my accounts come back?": how many have ordered more than once, how many ordered in the last 90 days, and how many orders an account places on average.
> - The **Do they come back** table groups accounts into cohorts by the quarter of their first order, so you can compare newer accounts with older ones.
> - Retention covers each account's whole history. The date range at the top of Pulse doesn't change it.

Winning an account is only the start. **Retention** shows how well your book holds on to accounts over time. It also shows which groups of accounts, by when they started, are still ordering.

New to Pulse? Start with [Pulse](https://docs.sparklayer.io/help/pulse.md) for how to open it.

## The Retention screen

| Part | What it shows / does |
| --- | --- |
| **Repeat rate** tile | The share of your accounts that have ordered more than once, with the count (for example, **5 of 6 ordered again**). |
| **Active last 90d** tile | The share of your accounts that ordered in the last 90 days, with the count (for example, **4 of 6 accounts**). |
| **Avg orders / account** tile | The average number of orders per account, over each account's lifetime. |
| **Cohorts** tile | How many cohorts there are, **by first-order quarter**. |
| **Do they come back** table | One row per cohort, oldest first: **Cohort** (a quarter, such as **2025 Q3**), **Accounts**, **Ordered again**, **Active last 90d** and **Lifetime spend**. **Ordered again** and **Active last 90d** show a share and a bar. |
| **Online orders only** | A reminder that the figures only include storefront orders. Hover over it for details. |
| **Download CSV** | Saves the cohorts, with the counts and shares. |

The table shows 20 cohorts a page.

## Check how well you keep accounts

1. In Pulse, click **Retention** in the sidebar.
2. Check **Repeat rate** and **Active last 90d** for your book as a whole.
3. In **Do they come back**, compare **Ordered again** and **Active last 90d** across cohorts.

**More detail**

A recent cohort with a low **Ordered again** share is normal: those accounts haven't had time to reorder. An older cohort with a low **Active last 90d** share has accounts that have drifted away. To find them, go to [Customers](https://docs.sparklayer.io/help/pulse/customers.md) and filter by the **Dormant** or **At risk** segment, or check [Reorder radar](https://docs.sparklayer.io/help/pulse/reorder-radar.md) for accounts that have gone quiet.

## How the figures are worked out

| Figure | How it's worked out |
| --- | --- |
| Cohort | The calendar quarter of the account's first order. |
| **Repeat rate** and **Ordered again** | Accounts with 2 or more orders, as a share of all accounts (in the cohort, for the table). |
| **Active last 90d** | Accounts whose last order was 90 days ago or less, as a share of all accounts (in the cohort, for the table). |
| **Avg orders / account** | All orders divided by the number of accounts, to 1 decimal place. |
| **Lifetime spend** | Everything the cohort's accounts have ordered, ever. |

Retention ignores the date range: it always uses every account's whole order history, as of today. The tiles count every account in your book, including accounts you've invited that haven't ordered yet. Those accounts have no first order, so they're in no cohort. Retention only uses orders placed through your storefront: see [Where the figures come from](https://docs.sparklayer.io/help/pulse.md#where-the-figures-come-from).

## FAQs

**Why don't the cohorts add up to the number of accounts in the tiles?**

The tiles count every account in your book, including invited accounts that haven't ordered yet. Cohorts only include accounts that have ordered, because a cohort is the quarter of the first order.

**Why doesn't the date range change Retention?**

Retention is about whether accounts come back over time, so it always uses each account's whole history, as of today. To see orders in a period, use [Orders](https://docs.sparklayer.io/help/pulse/orders.md).

**Why is my repeat rate lower than I expected?**

Inviting accounts lowers it until they order, because they count in the total but haven't ordered again. Orders taken by phone or email, or keyed into your ERP, aren't counted either.


---

# Account, order and quote details

URL: https://docs.sparklayer.io/help/pulse/records

Open any account, order, quote, invoice or cart in Pulse to see its details, prepare for a call, message the customer, chase payment or order for them.

> **Pulse is in early access.** Request it for your sales team. [Request early access](https://feedback.sparklayer.io/get-started?choice=now). [Try the interactive demo](https://www.sparklayer.io/pulse/).

> **Quick summary**
>
> - Click an account, order, quote, invoice, cart, trade application or product anywhere in Pulse and it opens in a panel on the right, over the page you're on.
> - Each panel has one main button at the foot, such as **Convert to order** on a quote, and the rest under **Actions**.
> - **Prep** opens a call prep sheet: the account's key figures, what to raise and what they buy, with **Call**, **Directions** and **Log outreach**.
> - Every ordering button opens the order in your storefront, signed in as that customer. Search everything with ⌘K (Ctrl+K on Windows).

## How the panels work

1. Click a record, such as an account name or an order row. Its panel slides in from the right.
2. Click a link inside the panel, such as the account name on an order, to open that record. Click the back arrow at the top left to return to the one before.
3. Use the main button at the foot of the panel, or click **Actions** for the others.
4. Click the cross, press Esc, or click outside the panel to close it.

Clicking a page in the Pulse sidebar closes any open panel.

## An account

The account panel is everything about one customer account in one place.

| Part | What it shows / does |
| --- | --- |
| Header | The account name, its health score and band, its segment (such as **Loyal** or **Dormant**), its customer group, email address (with a copy button), account number and phone number. Click the phone number to call it. On a phone, the number is hidden: use **Call** on the [prep sheet](#prepare-for-a-call-or-visit). |
| Facts | **Last order**, **Customer since**, **Location**, **Order rhythm** (such as **Every \~21 days**, or **No rhythm yet**), **Next order expected** (in red once the date has passed), **Usual order** (roughly what their average order is worth), **Open balance** (in red if any invoice is overdue, or **Nothing owed**), **Terms**, **Customer group** and **Sales agent**. |
| Tiles | **Total orders**, **Total spend** and **Avg order value** over the account's lifetime. |
| **Overview** tab | See [The Overview tab](#the-overview-tab). |
| **Timeline** tab | Every dated record for the account, as a list or a chart. See [The account timeline](#the-account-timeline). |
| **Orders** tab | Every order: **Date**, **Order #**, **Buyer**, **Items**, **Status**, **Payment** and **Value**, 20 a page, with **Status** (**Shipped**, **Processing**) and **Payment** (**Paid**, **Pending**) filters. Click one to open it. |
| **Receivables** tab | **Open money**: the account's invoices, with **Invoice**, **Dated**, **Due**, **Status** (such as **12d overdue** or **Within terms**) and **Value**. With none, it says **Nothing owed — the account is fully paid up.** |
| **Products** tab | **Top products**, with their usual quantity per order (or **occasional**), units, orders and value; **Cross-sell**, up to 6 products they don't buy, ranked by how many of your other accounts buy them; and **White space**, your 8 best-selling products they don't stock, each tagged **GAP**. |
| **Tasks & Notes** tab | The account's tasks and notes. The tab shows how many tasks are open. See [Tasks and notes](#tasks-and-notes). |

At the foot of the panel:

| Button | What it does |
| --- | --- |
| **New order** | Opens an empty order for the customer. See [Order for the customer](#order-for-the-customer). |
| **Call prep** (under **Actions**) | Opens the [prep sheet](#prepare-for-a-call-or-visit). |
| **Log outreach** (under **Actions**) | Records a call or visit. See [Log outreach](https://docs.sparklayer.io/help/pulse/task-list.md#log-outreach). |
| **Plan outreach** (under **Actions**) | Adds the account to today's [outreach plan](https://docs.sparklayer.io/help/pulse/task-list.md#plan-your-outreach). Shows **In the outreach plan** once it's there. |
| **Reorder their usual** (under **Actions**) | Opens an order with the account's usual basket. |

### The Overview tab

The **Overview** tab has these cards, in order:

| Card | What it shows / does |
| --- | --- |
| **Order history · 24 months** | The account's orders and GMV as a chart, with a month comparison strip underneath. |
| **Health** | The score out of 100 and its band, the part that's holding it back most (**Held back by…**), and a bar for each part: **Cadence**, **Spend trend** and **Engagement**. Click **How it's calculated** for the full working. See [How account health is scored](https://docs.sparklayer.io/help/pulse/customers.md#how-account-health-is-scored). |
| **What they buy** | **Regularly**: every product they've bought, most units first, with their usual quantity per order and the units they've bought across how many orders. **Not stocking yet**: up to 4 products they've never bought, ranked by how many of your other accounts buy them. Click a product to open it. |
| **Latest note** | The newest note on the account, with who wrote it and when. Click **All notes** or **Add a note** to go to **Tasks & Notes**. |
| **Buyers** | The people who order for the account, its [company users](https://docs.sparklayer.io/help/customers/company-users.md), with their role and whether they're still **Invited**. Click **Invite a buyer** to add one: see [Invite a buyer](https://docs.sparklayer.io/help/pulse/customers.md#invite-a-buyer). |
| **Addresses** | The account's billing and shipping address, and any you've added. Click **Add address** to add one. |

**Add an address**

1. On the **Addresses** card, click **Add address**.
2. Start typing in **Find address** and pick a match, or click **Enter address manually**.
3. Fill in **First name**, **Last name**, **Address line 1**, **Town / City** and **Country**. **Company**, **Address line 2**, **Postcode** and **Phone** are optional.
4. Tick **Set as default shipping address** or **Set as default billing address** if it is, then click **Save address**.

The address is labelled by what you ticked: **Billing & shipping**, **Shipping**, **Billing**, or **Address book** with neither.

### The account timeline

The **Timeline** tab lists every dated record Pulse holds for the account: when the account opened, every order, quotes raised, carts, customer replies, invoices issued and any you marked paid, promised or disputed, outreach you logged, tasks due and done, notes and reminders sent.

1. Click **List** for a table of **Date**, **Event** and **Value**, newest first, 15 to a page. Dates still to come are in italics. Click a row to open the record. A task or note opens the **Tasks & Notes** tab.
2. Click **Chart** to see the same records on a timeline, one lane per kind, such as **Orders** or **Quotes**. Each dot is a record, and a bar runs from a lane's first record to its last. A hollow dot is one still to come, such as a task due next week. Hover over a dot for its details, and click it to open the record.
3. Click a chip above, such as **Orders** or **Visits**, to show only that kind. Click more chips to add them, and click a chip again to hide it. With every chip off, all kinds show. Each chip shows how many records there are.

The kinds are **Orders**, **Quotes**, **Carts**, **Invoices**, **Visits**, **Tasks**, **Notes** and **Account**. Tasks with no due date aren't on the timeline. With nothing on file, it says **Nothing on file yet.**

Use the chart to see an account's rhythm at a glance: a steady row of order dots, and the gap where they stopped.

### Tasks and notes

The **Tasks & Notes** tab has 2 cards.

**Tasks** lists the account's tasks under **Overdue**, **Due today**, **Upcoming**, **No date** and **Done**. They're the same tasks as on your [Task List](https://docs.sparklayer.io/help/pulse/task-list.md).

1. Click **Add task**.
2. Enter the **Task**, and optionally a **Due** date (today if left empty) and **Notes**.
3. To show it in every rep's Task List, tick **Share with everyone**. Otherwise only you see it.
4. Click **Add task**.

Click the tick beside a task to mark it done. To delete one, click its bin icon, then **Delete task**: it's removed from every list. A shared task shows **Shared**.

**Notes** is for what was said on a call, or anything worth knowing about the account. Type in the box and click **Add note**. Nothing is sent to the customer. The newest note comes first, with who wrote it and when. A note can be up to 2,047 characters. Clicking a note's bin icon deletes it straight away, without asking.

Tasks and notes are saved in the browser you use, so they don't follow you to another device or browser.

## Prepare for a call or visit

The prep sheet is everything you need before you call or walk in. Open it with **Prep** on the Overview, today's queue, the outreach plan, the Task List or [Reorder radar](https://docs.sparklayer.io/help/pulse/reorder-radar.md), or with **Call prep** on an account or cart.

| Part | What it shows |
| --- | --- |
| Header | The account, its health and segment, how long it's been a customer and its payment terms. |
| Tiles | **Total orders**, **Total spend**, **Avg order value** (with their usual basket), **Since last order** (and how many days past their rhythm they are, or **on rhythm**), **Usual cadence** (days between orders, or **no rhythm yet**) and **Outstanding** (unpaid invoices, or **nothing owed**). |
| **What to raise** | Numbered talking points, worked out from the account's records. See the order below. |
| **What they buy** | **They always take**: up to 8 products from their usual basket, each with their usual quantity, units bought, when they last ordered it and what they've spent. **They don't take — others do**: up to 3 of your best sellers that at least 2 of your other accounts buy and they don't, with how many take them. Click a product to open it. |

The talking points come in this order, and only when they apply:

1. Overdue invoices, with the amount overdue: worth raising before taking a new order.
2. Up to 2 follow-ups you promised: the account's open tasks, with their due dates.
3. Open quotes, with how many and what they're worth.
4. How long they've been quiet, if they've gone quiet. Otherwise, how many days they're past their usual reorder, once they're at least 3 days past it.
5. Products similar accounts take that they don't.

With none of these, it suggests a relationship call. The talking points are worked out from the account's figures, not written by AI, so the same account always gets the same points.

At the foot of the sheet:

| Button | What it does |
| --- | --- |
| **Full profile** | Opens the [account panel](#an-account). |
| **Call** (under **Actions**) | Calls the account's contact number. Only shown when the account has one. |
| **Directions** (under **Actions**) | Opens the account's address in a map, in a new tab. Only shown when the account has an address. |
| **Print** (under **Actions**) | Prints the sheet to take with you: the key figures, what to raise, what they always take and what they don't. |
| **Log outreach** (under **Actions**) | Records how the call or visit went. See [Log outreach](https://docs.sparklayer.io/help/pulse/task-list.md#log-outreach). |
| **Reorder their usual** (under **Actions**) | Opens an order with the account's usual basket. |

## An order

The order panel shows one order in full.

| Part | What it shows |
| --- | --- |
| Header | The order number, its status (**Processing** or **Shipped**), its payment status (**Paid** or **Payment Pending**), the date and the account. **Waiting on your reply** shows when the customer has written and you haven't answered. |
| Latest message | When the order has messages: the newest one, with **Reply** or **Open timeline**. |
| **Items** | Each line: product, SKU, quantity, unit price and line total, with the **Order total**. Click a product to open it. |
| **Order economics** | **Units**, **Line items**, **Avg unit price** and **Vs buyer avg**: how the order compares with the account's average order. |
| **Addresses** | The billing and shipping addresses. |
| **Buyer** | The account, with **Full profile** and **Their top products**. |
| **Timeline** | Messages with the customer, notes for your team and what happened to the order. See [Message the customer](#message-the-customer-on-an-order-or-quote). |

The main button is **Reorder**, which opens a new order with the same lines. Under **Actions**: **View invoice** (if the order has an unpaid invoice), **New order**, **Open buyer profile** and **Reorder their usual**. See also [Orders](https://docs.sparklayer.io/help/pulse/orders.md).

## A quote

The quote panel shows one quote, with its lines and the account.

| Part | What it shows / does |
| --- | --- |
| Header | The quote reference, its status, when it was raised, how many days it's been open, when you last sent a reminder, and the account. A quote that has been open 14 days or more is marked **Stale** with its age, such as **Stale · 18d**. **Waiting on your reply** shows when the customer has written and you haven't answered. |
| Status | Click the status to change it: **Open** (no reply yet), **Awaiting customer** (with the customer), **Accepted** (off the pipeline) or **Declined** (kept for the record). |
| Latest message | When the quote has messages: the newest one, with **Reply** or **Open timeline**. |
| **Quoted lines** | Each line and the **Quote total**. On an open quote, **Amend** lets you change quantities or remove lines. |
| **Quote economics**, **Addresses**, **Buyer** | As on an order. |
| **Timeline** | Messages with the customer, notes for your team and what happened to the quote. See [Message the customer](#message-the-customer-on-an-order-or-quote). |

On an open quote, the main button is **Convert to order**, which puts the quote's lines, at the quoted prices, into an order for the customer. Converting doesn't change the quote's status: set it to **Accepted** yourself. Under **Actions**: **Send reminder** (see [Send a reminder](#send-a-reminder)), **New order for** the account (an empty order that leaves the quote as it is) and **Delete quote**. An accepted or declined quote has no **Convert to order** or **Send reminder**.

Status changes, amendments and deletions are saved to the quote in the Quoting Engine, and the customer sees them. To change a quote's status, amend it, delete it or convert it, see the steps in [Quotes](https://docs.sparklayer.io/help/pulse/quotes.md#change-a-quotes-status).

## Message the customer on an order or quote

Every order and quote has a **Timeline** card at the foot of its panel. It holds your messages with the customer, notes for your team, and what happened to the record, such as **Order placed**, **Invoice issued**, **Quote raised**, **Status set to Accepted** or **Quote reminder sent**. The newest day comes first.

1. Open the order or quote. If the customer is waiting, click **Waiting on your reply** or **Reply** to jump to the reply box.
2. Choose **Message** and the customer's name to write to them, or **Internal note** to write to your team.
3. Type your message, then click **Send as email** or **Add note**. You can also press ⌘Enter (Ctrl+Enter on Windows).

**More detail**

- **Send as email** emails the customer and shows the message on the order or quote in their account, when **Timeline and communications** is on at **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app. The box says which email address it goes to. See [Order timeline and messages](https://docs.sparklayer.io/help/customers/timeline.md).
- A note is marked **Internal note**, and only your team sees it.
- Each message shows who wrote it, as **Sales agent** or **Customer**. A customer message you haven't seen yet is marked **New**.
- A message or note can be up to 2,047 characters.
- With no messages yet, the card says **No messages yet. Write the first one above.**

## An invoice

The invoice panel shows one invoice, where its status comes from and what it's for.

| Part | What it shows / does |
| --- | --- |
| Header | The invoice number, its status (such as **28d overdue**, **Within terms**, **Paid** or **Payment promised**), the date, the account and the payment terms. |
| Status | Click the status to change it: **Paid** (payment received), **Payment promised** (a date is promised), **Disputed** (being queried) or **Outstanding** (back to open). |
| **Invoice** | **Amount**, **Dated**, **Terms** and **Due** (in red when overdue), with the source of the payment status. Notes such as **Marked Promised by you on …** or **Reminder sent …** appear here. |
| **What it's for** | The order the invoice covers, with its lines and **Open order**, or a note that it's a statement invoice for a balance carried forward. |
| **Buyer** | The account, with **Full profile**. |

Click **Mark as paid** to record a payment. Under **Actions**: **Send reminder** ([Send a reminder](#send-a-reminder)), **Add a task** (a task dated today to chase it) and **Open buyer**. A paid invoice has no **Mark as paid** or **Send reminder**.

A status you set on an invoice is a note beside the status synced from your accounting system; it doesn't change your accounting system. Only **Paid** takes an invoice out of what's owed: a promised or disputed invoice still counts as outstanding, and as overdue once it's past its due date. For the steps, see [Mark an invoice as paid](https://docs.sparklayer.io/help/pulse/receivables.md#mark-an-invoice-as-paid) and [Record a promised payment or a dispute](https://docs.sparklayer.io/help/pulse/receivables.md#record-a-promised-payment-or-a-dispute). 

## A cart in progress

A cart is a basket a customer has started in your storefront but not ordered. It counts as abandoned once nobody has touched it for 3 days. You can change the number of days (1, 2, 3, 5, 7, 14 or 30) with **Abandoned after** on [Carts](https://docs.sparklayer.io/help/pulse/carts.md).

| Part | What it shows |
| --- | --- |
| Header | The account, the cart's reference, where it was built, and **In progress** or **Abandoned**. |
| **In the basket** | Each line and the **Basket total**. |
| **Timing** | **Started**, **Last touched** (in red when abandoned), **Built in** (such as **Storefront** or **Quick order**) and **Vs their usual** (how it compares with their average order), with a line such as **Untouched 5 days · abandoned**. |
| **Buyer** | The account, with **Full profile** and their top products. |

The main button is **Finish it for them**, which signs you in as the customer and takes over their cart, so you can edit it and place the order. Under **Actions**: **Add a nudge task** (a task dated today to remind them) and **Call prep**.

Carts come from your store's live data. A cart leaves Pulse once it's ordered.

## A trade application

A trade application comes from your storefront's trade application form. 

| Part | What it shows |
| --- | --- |
| Header | The company, its status (**New**, **In review**, **Approved** or **Declined**), the contact and country. |
| **Application** | When they applied, and what they filled in: **Company**, **Contact**, **Email**, **Phone**, **Country**, **Trade** and **Interested in**. |
| **What they asked about** | The product ranges they named, with how many of your accounts take each and what it sells. Click one to open it. |
| **On approval** | What approving does: creates the account on a customer group's pricing and terms, emails an invite to the contact, and lists them under **Customers**. |

On a new or in-review application, the main button is **Approve & invite**. The other options are **Decline**, **Add a task to call** (a task dated today, which also moves a new application to **In review**) and, on a new one, **Mark in review**. An approved application shows **Open the account**; a declined one shows **Reopen**, which puts it back to **New**. For the steps, see [Review a trade application](https://docs.sparklayer.io/help/pulse/customers.md#review-a-trade-application). 

## A product

The product panel shows how one range or variant sells, and who buys it.

| Part | What it shows / does |
| --- | --- |
| Header | The product name, with **Range** and how many variants it has, or the variant's SKU and the range it's part of. When it was last ordered. |
| Tiles | **Units** and **Revenue** all time, how many order lines it's **On**, and how many of your accounts buy it (**Buyers**). |
| **Movement · 24 months** | Units and revenue over time. |
| **Variants** | For a range, each variant. Click one to open it. |
| **Who takes it** | The accounts that buy it, each with the units they've bought, when they last ordered it and what they've spent on it. Under it, **Not stocking yet** lists the accounts that have never bought it, with their health, when they last ordered anything and their average order value: worth offering it to. Click an account to open it. |

The main button is **Add to a buyer's cart**. It asks **Add to whose cart?**: search for and choose an account, and Pulse opens an order for them with the product at their usual quantity. Each account is marked **stocks it** or **new line**. Under **Actions**, **View product** opens the product in your storefront, in a new tab. See also [Products](https://docs.sparklayer.io/help/pulse/products.md). 

## A breakdown

Clicking a tile, a chart point or a figure opens a breakdown: the records that make up that number.

| Part | What it shows |
| --- | --- |
| Header | What the figure is, such as **Your month so far**, with the count, total and period. |
| **By account** | Each account's share of the total, when more than one account is in it. |
| **By range** | For a product chart, the units of each range. |
| List | The orders, quotes, invoices, carts or accounts behind the figure, with a **Total**. Click a row to open it. |

Breakdowns built from orders show **Online orders only**: see [Where the figures come from](https://docs.sparklayer.io/help/pulse.md#where-the-figures-come-from).

## Send a reminder

Pulse drafts a reminder for an open quote or an unpaid invoice, for you to send from your own email.

1. On the quote or invoice, choose **Send reminder** from **Actions**. The button is highlighted on a stale quote or an overdue invoice.
2. Check the draft: **To**, **Subject** and the message, which lists the quote's lines and total, or the invoice's amount, due date, terms and how many days it's overdue. Edit the message if you like.
3. Click **Copy**, then paste it into a new email and send it.
4. Back in Pulse, click **Mark as sent**.

Marking it sent records **Reminder sent** on the quote or invoice and on the account's timeline, and adds a task to check on it in 3 days. The button then reads **Chase again**.

**More detail**

Pulse doesn't send the email itself: it only records that you did. **Copy** copies the **To** address, the **Subject** and the message together.

## Order for the customer

Every ordering button in Pulse signs you in as the customer and opens the order in your storefront, so you order at their prices with their payment methods.

| Button | Where | What goes in the basket |
| --- | --- | --- |
| **Order** | Overview, today's queue, Reorder radar | Their usual basket |
| **Reorder their usual** | Account, prep sheet, order | Their usual basket |
| **New order** | Account, order | Nothing: an empty order |
| **New order for** the account | Quote | Nothing: the quote is left as it is |
| **Reorder** | Order | The same lines as that order |
| **Convert to order** | Quote | The quote's lines, at the quoted prices |
| **Finish it for them** | Cart | The customer's own cart, which you take over |
| **Add to a buyer's cart** | Product | The product at their usual quantity. For a range, the variants in their usual basket, or else its best seller |

1. Click the button. Pulse switches to the order, with the customer's name in the chip at the top. Except for an empty order, a message confirms what's ready, for example "Their usual basket is ready to review".
2. Check the quantities, then check out or submit a quote. See [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md).
3. To go back to Pulse, click the **Dashboard** tab.

## Search Pulse

Search finds any account, order, quote, invoice, cart, trade application, product or Pulse page.

1. Press ⌘K (Ctrl+K on Windows), or click **Search** at the top of the Pulse sidebar. On a phone, tap the search icon at the top of the page.
2. Start typing, such as an account name, a contact, a product name or SKU, or an order number like `#1234`.
3. Use the up and down arrow keys to move through the results, and Enter to open one. Or click it.

**More detail**

- Before you type, search shows your last 6 searches under **Recent** (click **Clear** to forget them), the last 8 records you opened under **Recently viewed**, and some ideas under **Try searching**.
- Each result is labelled with what it is, such as **Product** or **Order**, and the 10 best matches are shown.
- Typing an exact order number jumps straight to that order.
- Tasks aren't searched. Find tasks on your [Task List](https://docs.sparklayer.io/help/pulse/task-list.md).
- Press Esc to close search.

## FAQs

**Where have the other buttons gone?**

Each panel shows its main button at the foot and puts the rest under **Actions**. Click **Actions** to see them.

**Does converting a quote to an order mark it accepted?**

No. **Convert to order** puts the quote's lines into an order and leaves the quote as it was. Once the customer has ordered, click the quote's status and choose **Accepted**.

**Does Pulse email the reminder for me?**

No. Pulse drafts the reminder for you to copy into your own email. **Mark as sent** records that you sent it and adds a task to check on it in 3 days. See [Send a reminder](#send-a-reminder).

**Does marking an invoice paid in Pulse update Xero or QuickBooks?**

No. Your accounting system stays the record of what's paid. What you mark in Pulse is a note beside the synced status, so your team can see you've followed it up.

**Why is an account's usual basket different from its average order?**

The usual basket is what its next order is likely to be: the products on at least half of its orders, at their usual quantities. The average order value includes one-off and unusually large orders. See [how the usual basket is worked out](https://docs.sparklayer.io/help/pulse/reorder-radar.md#how-the-figures-are-worked-out) on Reorder radar.


---

# Sales rep ordering

URL: https://docs.sparklayer.io/help/sales-ordering

How sales reps order on behalf of B2B customers: switch to a customer, use the Catalog for bigger orders, or sell in person with Counter mode.

> **Quick summary**
>
> - A sales rep (a **sales agent** in SparkLayer) signs in to your store, chooses a B2B customer and orders on their behalf, at the customer's own prices.
> - Reps take an order [in the cart](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md) (by phone or email), with [Counter mode](https://docs.sparklayer.io/help/sales-ordering/counter-mode.md) (face to face) or from the [Catalog](https://docs.sparklayer.io/help/sales-ordering/catalog.md) (bigger orders, by picture).
> - To plan who to call and keep track of a whole book of accounts, reps use [Pulse](https://docs.sparklayer.io/help/pulse.md). To make someone a sales agent and choose what they can do, see [Sales rep setup](https://docs.sparklayer.io/help/sales-reps.md).This section is for sales reps taking an order for a customer. It covers how ordering works, which tool to use and what reps can do for a customer.## How it worksSales agent ordering, sometimes called order masquerading, brings your sales team's orders into your online store. A sales agent is a customer account in your store with a sales agent role.

When they sign in, they choose a customer and act as that customer from then on. They see the customer's prices and payment methods, and the order is placed against the customer's account, not their own.How a sales rep places an order:

1. **Sign in**: The rep signs in to your store with their own account
2. **Choose a customer**: They pick a B2B customer from their open orders or a search
3. **Build the order**: They add products at the customer's prices
4. **Check out or quote**: The order or quote is placed for the customerYou can try it on our [B2B demo store](https://demo.sparklayer.io/pages/b2b-login-register).## Where reps workEverything happens inside your storefront's SparkLayer widget, at the customer's prices. Pick the tool that fits how the customer is buying.| Tool                                                              | Use it for                                                                                                   | Where the rep finds it                         |
| --- | --- | --- |
| [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md) | Taking an order by phone or email, finishing a customer's cart, or raising a quote. | **My Cart** and **My Customers** in the widget |
| [Catalog and Quick Order](https://docs.sparklayer.io/help/sales-ordering/catalog.md) | Building a larger order from an image-led product grid, with search and collection filters. | The **Catalog** tab |
| [Counter mode](https://docs.sparklayer.io/help/sales-ordering/counter-mode.md) | Selling face to face, at a trade counter or a trade show: pick the account, scan or tap products, check out. | **Counter** on the **Catalog** tab |
| [Pulse](https://docs.sparklayer.io/help/pulse.md) (early access) | Running a book of accounts: orders, quotes, receivables and who to contact next, in one workspace. | The **Dashboard** tab |You need the Starter plan or above for the Catalog and Counter mode, as for sales agents themselves. See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).Pulse is on every paid plan, for reps with a sales agent seat. It's in early access: request it from the [Pulse](https://docs.sparklayer.io/help/pulse.md) page.## What sales reps can doOnce they've chosen a customer, a sales agent can:| Action | Details |
| --- | --- |
| **View products** | See products at the B2B prices assigned to the customer. |
| **Place an order** | Check out with the customer's payment methods, or submit a quote. |
| **Shopping lists** | Save, edit and load the customer's [shopping lists](https://docs.sparklayer.io/help/ordering/shopping-lists.md). |
| **Address book** | Add and edit the customer's addresses, if the customer's group allows address editing. |
| **Re-order** | Re-order from an existing order in the customer's account. |
| **Persistent cart** | Products added to an order stay in the customer's cart until they check out or change it, so the rep can come back to it later. |
| **Company users**   | Invite and manage the customer's [company users](https://docs.sparklayer.io/help/customers/company-users.md).                                                |With the **Sales administrator** role, or a custom role with the matching permissions, they can also [change unit prices](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#change-a-unit-price), [add custom items](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#add-a-custom-item), [set a custom shipping rate](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#set-a-custom-shipping-rate), [override quantity rules](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#override-quantity-rules) and [add new customers](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#add-a-new-customer).## In this section- [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md): Switch to a customer, build the order and check out
- [Catalog and Quick Order](https://docs.sparklayer.io/help/sales-ordering/catalog.md): Build orders from an image-led product grid
- [Counter mode](https://docs.sparklayer.io/help/sales-ordering/counter-mode.md): Sell in person at a trade counter or show## Next steps- [Pulse](https://docs.sparklayer.io/help/pulse.md): Plan who to call, chase quotes and invoices, and see how each account is trading (early access)
- [Sales rep setup](https://docs.sparklayer.io/help/sales-reps.md): Make someone a sales agent, choose their customers and set roles


---

# Order for a customer

URL: https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer

Switch to a B2B customer in your store, build their order at their prices, change unit prices or shipping, then check out or submit a quote on their behalf.

> **Quick summary**
>
> - Sales agents order for a customer from the storefront widget in 3 steps: pick the customer in **My Cart** or **My Customers**, add products, then click **Checkout** (or **Submit Quote**).
> - The **Ordering for** button at the start of the cart's search row shows who you're ordering for. Click it to switch customer.
> - Sales administrators (or a custom role with the permissions) can also change unit prices, add custom items, set a custom shipping rate, override quantity rules and add new customers.

## How it works

Once you choose a customer, everything you see is theirs: prices, payment methods, credit, addresses and order history. The order is placed against the customer's account, not yours.

How an order for a customer works:

1. **Choose a customer**: From your open orders or a search
2. **Build the order**: Add products at the customer's prices
3. **Adjust**: Change prices, shipping or quantities if your role allows
4. **Check out or quote**: The order or quote is placed for the customer

## Choose a customer

Start every order by choosing who it's for.

1. Sign in to your store with your sales agent account and open **My Cart**.
2. On the **Order builder** screen, pick a customer under **Open orders**, or search for one and click **Start order**.
3. Their cart opens, with their name in the **Ordering for** button.

**More detail**

You can also pick a customer from the **My Customers** tab: search, then click **Log in**, or click **Login** next to a recently accessed account. This opens the customer's account in **My Account**. 

In [Pulse](https://docs.sparklayer.io/help/pulse.md), every ordering button, such as **Order** or **Reorder**, chooses the customer for you and opens their cart. See [Order for the customer](https://docs.sparklayer.io/help/pulse/records.md#order-for-the-customer). Both screens are described under [The Order builder and My Customers tab](#the-order-builder-and-my-customers-tab).

## Check who you're ordering for

The **Ordering for** button shows who you're ordering for. It sits at the start of the search row in **My Cart**, with the customer's initials and name.

1. Hover over or focus the button to see the customer's full name.
2. Click it to [switch customer](#switch-to-another-customer).

**More detail**

Prices, credit and history follow the chosen account, so check the button before you add products. It replaces the "You're signed in as" banner and the **Switch Account?** link of earlier versions.

## Switch to another customer

1. Click the **Ordering for** button.
2. On the **Order builder**, pick another customer, or search for one.

**More detail**

Each customer's cart is kept as you left it, so you can move between several customers' orders and come back to each. You can also act as a different customer on each of your devices.

## Cart locking

A customer's cart can only be changed by one sales agent at a time. When you choose a customer, their cart is locked to you. If another sales agent has the same customer open, they see:

> You cannot update the cart because it is being processed by a sales agent

The cart stays locked to whichever agent has it open. To carry on, the other agent switches to another customer, or you wait until they've finished.

My Cart can also show who last edited the cart, for example **This cart is being edited by a sales agent**, with **Take control** to make your own changes. See [Cart locking in My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md#cart-locking). 

Shared logins make this more likely, because two people signed in as the same agent can each open the same customer. Give every person their own sales agent login. See [Add a sales agent](https://docs.sparklayer.io/help/sales-reps.md#make-someone-a-sales-agent).

## Add products

Add products as a customer would, at the customer's prices:

| How | Where |
| --- | --- |
| Search by name, SKU or barcode | The search box in **My Cart**. |
| Browse an image-led product grid | The **Catalog** tab. See [Catalog and Quick Order](https://docs.sparklayer.io/help/sales-ordering/catalog.md). |
| Load a shopping list | **Actions** in **My Cart**. See [Shopping lists](https://docs.sparklayer.io/help/ordering/shopping-lists.md). |
| Re-order a past order | The customer's order history in **My Account**. See [Reorder](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md#reorder). |
| Scan barcodes, upload a file or forward an email | **Actions** in **My Cart**. See [Intelligent Cart (AI)](https://docs.sparklayer.io/help/ordering/intelligent-cart.md). |

**More detail**

Personal shopping lists are a quick way to start customer orders: save a list in your own account, then choose a customer and load the list to fill their order.

## Check out for the customer

1. In **My Cart**, click **Checkout**.
2. Under **Details**, choose the customer's shipping address and fill in any other fields, such as a purchase order number.
3. Under **Review & Pay**, choose a **Shipping Method** and one of the customer's payment methods.
4. Click **Complete Order**.

**More detail**

The checkout steps are **Cart**, **Details**, **Review & Pay** and **Complete**, as for the customer. The payment methods are the ones the customer's [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md#choose-payment-methods) allows. If the customer pays upfront, they're emailed to pay.

### How the order and payment work

**Shopify:**

When a sales agent places an order, it arrives in Shopify as a **draft order** with the customer's details filled in, whatever the payment method. It stays a draft until payment is made or you act on it.

| Payment method | What happens |
| --- | --- |
| **Pay by Invoice** | A draft order is created for you to process. |
| **Pay on Account** | A draft order is created for you to process. |
| **Pay Online by Card** | A draft order is created and the customer is emailed to pay. |

When the customer needs to pay, Shopify emails them their order with a **Complete your purchase** button. This uses the "Send invoice" feature of draft orders (see Shopify's guide to [sharing a checkout link](https://help.shopify.com/en/manual/orders/create-orders#share-checkout-link-with-customers)). Once they pay, the order moves to your Shopify orders as paid.

To change the email, go to **Settings > Notifications** ([open in the Shopify admin](https://admin.shopify.com/settings/notifications)) and edit the **Draft order invoice** template.

If the customer hasn't paid, or you take payment another way, open the draft order in Shopify and click **Resend invoice**, or use **Collect payment** to mark it as paid.

**Other platforms:**

How orders arrive depends on your platform: see the [developer docs](https://docs.sparklayer.io/developers.md).

## Submit a quote

Instead of placing an order, you can submit the cart as a [quote](https://docs.sparklayer.io/help/ordering/quoting.md) for the customer. This needs the **Create quotes** permission, and quotes turned on at **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app (Pro and Enterprise, or the Quoting Engine add-on on Starter and Growth).

1. In **My Cart**, click **Submit Quote**, next to **Checkout**.
2. Work through the checkout steps. Each one shows **This order will be submitted as a quote**.
3. Click **Submit Quote**.

**More detail**

The quote then follows your Quoting Engine process: see [Work on a quote](https://docs.sparklayer.io/help/ordering/work-on-a-quote.md).

## Change a unit price

Sales administrators can change a product's unit price on a cart line. This gives a one-off price without changing your price lists. It needs the **Change quoted prices** permission.

1. Click the unit price on the cart line (it's underlined with dots).
2. In **Edit unit price**, choose **Fixed price** or **Percentage off**, and enter the price or percentage.
3. Click **Save price**.

**More detail**

- The line under the field shows what you're setting: the percentage off the original price, or the new unit price.
- A percentage is always taken from the original price, so 10% off twice is still 10% off.
- The option you used last stays chosen for the next line.
- **Reset** puts the original price back in the field.
- If the line has quantity rules, its label changes from **Qty rules apply** to **Qty rules overridden**. 
- You can set a price above the original as well as below it.

## Add a custom item

Sales administrators can add items that aren't in your catalogue, such as special instructions, products without a SKU or another charge. It needs the **Add custom items** permission.

1. In **My Cart**, click **Actions**, then **Add custom item**. 
2. Enter the item's **Name**, its **Cost** per unit and the **Quantity**.
3. Click **Add**.

**More detail**

A custom item can have a price or be free. You can then change its unit cost and quantity, or remove it.

## Set a custom shipping rate

Sales administrators can set their own shipping cost for an order, without changing your [shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md). It needs the **Change shipping** permission.

1. At checkout, under **Review & Pay**, click **Add custom rate** next to **Shipping Method**.
2. Enter a description, such as "Pallet delivery", and the amount. Enter 0 for free shipping.
3. Click **Add**.

**More detail**

- The rate is added to the shipping methods with a **Custom** label, and chosen for the order. Without a description, it's called "Custom rate".
- Your platform's admin shows the shipping as custom shipping. If other systems read your orders, such as an ERP, test how they handle it before you rely on it.

## Override quantity rules

Sales administrators can ignore a product's [pack size and minimum or maximum quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md) and enter any quantity. It needs the **Ignore product rules** permission.

1. Enter the quantity you need on the cart line.
2. Tick **I acknowledge that I've made changes to requirements in this order**.
3. Click **Checkout**.

## Add a new customer

Sales administrators can create a customer from your store, then order for them straight away. It needs the **Create customers** permission.

1. Open the **My Customers** tab and click **Actions**, then **Add a new customer**.
2. Enter the customer's **First name**, **Last name**, **Email** and **Company**.
3. Click **Add new customer**.

**More detail**

The new customer gets the same settings as the sales agent who created them: price lists, discount percentage, customer group, sales agent groups and default addresses. To change them, edit the customer afterwards, for example by giving them a different customer group tag.

| Account status | What happens |
| --- | --- |
| No account on your store | They're emailed an invitation to set up their account. |
| Already has an account | They sign in with their existing details. |

**Shopify only:**

On Shopify, the invitation is Shopify's account activation email, which you can edit at **Settings > Notifications** ([open in the Shopify admin](https://admin.shopify.com/settings/notifications)). To stop invitations being sent, turn on **Don't send Shopify's customer invite** at **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app.

## Order for yourself

Sales agents can also order for their own account, for example to buy a sample for a customer demonstration. Their prices come from the price list of their own [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md).

1. In **My Cart**, switch to your own account. 
2. Add products and check out like any customer.

**More detail**

This needs version `1.4.0` or later of the [SparkLayer Core Script](https://docs.sparklayer.io/developers/frontend.md).

## Track sales agent orders

Orders placed by sales agents carry extra data, so you can filter and report on them, or pass the data to your other systems.

**Shopify only:**

On Shopify, it's on the draft order, and on the completed order once payment is taken:

| Data | Details |
| --- | --- |
| **Tags** | `agent` (an agent order), `agent-` plus the start of the agent's email (for example `agent-contact`), `agent-` plus the agent's email domain (for example `agent-sparklayer.io`), and `b2b` (a B2B order). |
| **B2B Sales Agent Account ID** | The agent's accounting ID, if they have one. |
| **B2B Sales Agent Email** | The sales agent's email address. |
| `sparkPaymentType` | Added to all B2B orders, showing the payment type the agent chose. |

The fields appear under **Additional details** on the order.

Sales agents can also export order activity to a CSV file from the activity list in [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md#export-orders), with the **Download** menu: choose **Activity** or **Activity with line items**.

## The Order builder and My Customers tab

Sales agents use these 2 screens to find and switch customers.

### The Order builder

The **Order builder** is what you see when you open **My Cart** without an order on screen, and when you click the **Ordering for** button. 

| Part | What it shows / does |
| --- | --- |
| Search | **Search buyers by name, email or account number**. Click **Start order** next to a result. |
| **Recently accessed accounts** | The last five customers you opened, with their email and **Last order** date. Click **Open** to carry on an open order, or **Order** to start one. |
| **View all customers** | Opens your full customer list. |
| **Open orders** | Customers with an order in progress, with its **Lines**, **Units** and **Amount**. The customer you're ordering for is marked **Current**. Click a row to carry on. |
| **Recent activity** | The latest orders across your customers, with **Reference**, **Submitted on**, **Status** and **Amount**. Filter by **Status**: **All**, **Shipped** or **Processing**. |
| **Back to order** | Returns to the cart of the customer you're ordering for. |

### The My Customers tab

Sales agents see a **My Customers** tab in the widget, headed **Sales Agent Ordering**.

For a sales rep with [Pulse](https://docs.sparklayer.io/help/pulse.md), the widget's tabs are **Dashboard**, **Catalog** and **Order** instead, with no **My Customers** tab: **Dashboard** opens Pulse, and **Order** is the cart. See [Open Pulse](https://docs.sparklayer.io/help/pulse.md#open-pulse).

| Part | What it shows / does |
| --- | --- |
| Search | **Search customers by name, email or account number**. Click **Log in** next to a result. |
| **Actions** | **Add a new customer** (see [Add a new customer](#add-a-new-customer)). |
| **Recently accessed accounts** | Customers you've opened, with **Last Login** and a **Login** button. |
| **Recent Activity** | Recent orders across your customers, filtered by **Status**. Click a reference to see the order's lines. |

## FAQs

**Another person is editing the same cart**

[Cart locking](#cart-locking) stops two people changing a cart at once. My Cart shows who last edited it, for example **This cart is being edited by a sales agent**, or the warning "You cannot update the cart because it is being processed by a sales agent". Wait, or click **Take control** to make your own changes. If you share a login with another agent, ask for your own.

**Can I work on several devices?**

Yes. You can use the same login on more than one device, pick up an order where you left off, or act as a different customer on each device.

**Why can't I change a price or add a custom item?**

Your role doesn't include that permission. Ask an admin to check your role at [Roles and permissions](https://docs.sparklayer.io/help/sales-reps/roles.md).

**Why can't I choose Pay Online by Card?**

You only see the payment methods the customer's group allows. To offer card payment, turn it on for their group: see [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md).

**Why isn't my custom shipping rate added to the total?**

**Shopify only:**

The products in the order are set as not physical in Shopify. SparkLayer works out the order total with Shopify, and Shopify doesn't charge shipping on products that don't need shipping. So the rate shows on the **Shipping** line but isn't added to the total. This applies to quotes too.

1. In Shopify, open a product that ships and select a variant.
2. In the **Shipping** section, turn on **Physical product**, then save. Repeat for each variant.

For a lot of products, select them in **Products**, click **Bulk edit**, add the **Requires shipping** column, tick the boxes and save.


---

# Counter mode

URL: https://docs.sparklayer.io/help/sales-ordering/counter-mode

Serve trade customers in person with Counter mode: a full-screen till to pick the account, scan or tap products, check credit and pay on account or by card.

> **Counter mode is in early access.** Request it for your sales team. [Request early access](https://feedback.sparklayer.io/get-started?choice=now).

> **Quick summary**
>
> - Counter mode is a full-screen till for sales reps serving customers face to face: at a trade counter, in a showroom or on a trade show stand.
> - Open it with the **Counter** button on the [Catalog](https://docs.sparklayer.io/help/sales-ordering/catalog.md) tab. It's for sales reps only; customers' **Quick Order** tab doesn't have it.
> - Pick who's buying, scan or tap products, and watch the account's credit position as you go. Then check out on Net terms, send a card payment link, or submit a quote.
> - It works with a barcode scanner, and on a tablet or phone as well as a desktop. Counter mode needs the Starter plan or above.

## How it works

Counter mode is the same ordering you do as a sales rep, laid out for speed at a counter. It has large tap targets, a scan field that's always ready, and the account's credit in view. Prices, credit and order history all follow the account you pick, so the customer gets their own prices and payment terms.

Serving a customer at the counter:

1. **Who's buying?**: Search for the account, or pick a recent or held order
2. **Add products**: Scan barcodes, tap products or their usual buys
3. **Check the order**: Lines, discounts and the credit position in the order panel
4. **Check out**: Details, then Review & Pay, or submit a quote
5. **Done**: Print a receipt and serve the next customer

## Before you start

You need:

- **A sales rep account** that can [order for customers](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md). Your store owner or admin sets this up: see [Sales rep setup](https://docs.sparklayer.io/help/sales-reps.md).
- **A barcode scanner (optional)** that types into the computer like a keyboard, such as a USB or Bluetooth scanner. A scan matches a product's barcode or its SKU.
- **Payment methods** for the customer's group: **Pay with Net terms** needs payment on account; **Pay online by card** needs upfront card payment. See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md). 

## Open Counter mode

1. Open the SparkLayer widget and go to the **Catalog** tab.
2. Click **Counter** in the header. The till opens full screen.

**More detail**

Click **Exit** at any time to go back to the widget, where you're ordering for the customer you were serving. The till keeps the order you were building: click **Counter** again to pick it up.

## Choose who's buying

Start each sale by choosing the account. The till opens on **Who's buying?**, where each account shows its account number and where it stands:

| Shown | Means |
| --- | --- |
| **Nothing outstanding** | No unpaid invoices. |
| _amount_ **on account** | Unpaid invoices, all within terms. |
| _amount_ **overdue** | At least one invoice is past its payment terms. |
| **Recent** | You served this account recently, so it's near the top. |

1. Type in **Search accounts…** to find the customer by name or account number.
2. Tap the account. The order screen opens at their prices.

**More detail**

Orders you've put on hold are listed above the search, under **Held at this counter**, with how long ago they were held. Tap **Resume** to carry on. If you go back to **Who's buying?** with an order open, **Order open for** shows it: tap **Back to this order**, or **Clear it**. Choosing another account moves the open order's items to them.

## Add products

The order screen has the products on the left and the order on the right. Add products in any of these 4 ways:

| Way | How |
| --- | --- |
| Scan | Scan a barcode at any time. The till catches it even when the scan field isn't selected. A banner confirms the product, or says no code matched and shows search results instead. |
| Search | Type in **Scan a barcode, or search the range…**, or narrow the products with the collection filter (**All collections**), which on Shopify follows your [navigation menu](https://docs.sparklayer.io/help/platforms/shopify/catalog-collections.md). |
| Tap | Tap a product's tile or price to add one. The tile flashes and the total updates. |
| Usual buys | The **_account_ usually buys** strip shows up to six products the account orders most. The first tap adds their usual quantity (shown as "usually 36"); each tap after that adds one. |

### Choose a variant

A product with more than one variant opens **Which one?**, so you choose the variant the customer is holding rather than a default.

1. Tap the variant. Out-of-stock variants can't be chosen.
2. For a product with many variants, such as shoes in several colours and sizes, tap the colour first, then the size. Sizes that are out of stock are struck through and low ones are marked.

**More detail**

To jump straight to one, type in **Search size, colour or SKU**, for example "black 9". **Show all** lists every variant at once.

## Check the order

As you add products, the order panel on the right keeps track. It works like [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md):

| Part | What it shows / does |
| --- | --- |
| **Account** | Who you're serving. Tap **Change account** to go back to **Who's buying?**. |
| **Actions** | **Hold this order**, **Discount the order**, **Open invoices** and **Clear the order**. |
| Credit position | The account's balance against its terms and credit limit, updated as the order grows (see below). |
| Lines | Each product with its price each, line total, quantity stepper, SKU and a bin to remove it. |
| Volume break | Under a line, a nudge such as "+4 more → $5.10 each (Save 15%)". Tap it to take the line to that break. |
| **Discounts & codes** | Discounts on the order, with a count of those applied. |
| Totals | Subtotal, tax and the total, with the number of items and lines. |
| **Submit Quote** and **Checkout** | The two ways to finish. |

Volume breaks apply as you go: a line is priced at the break its quantity reaches, as in the cart.

### Credit position

| Message | What you can do |
| --- | --- |
| **Nothing outstanding**, or _amount_ **on account, all within terms** | Any payment method. |
| _amount_ **overdue**, _N_ **days past terms** (14 days or more) | Any payment method, with a warning. |
| _amount_ **overdue**, _N_ **days past terms** (60 days or more) | **Can't go on account — take payment or save a quote.** |
| **Over credit limit** (with this order) | **Can't go on account — take payment or save a quote.** |
| **No credit information for this account** | Any payment method, with a warning. |

To see the account's open invoices, tap the credit position, or choose **Actions > Open invoices**. Each invoice shows its amount, and how many days it's past its terms or how many days are left to pay.

### Discount a line or the order

1. For one line, tap its price ("$x each"). For the whole order, choose **Actions > Discount the order**, or **Discounts & codes**.
2. Choose **Percentage** or **Fixed amount** and enter the value.
3. Enter a **Reason**, such as a damaged box or a price match. It's required.
4. Tap **Apply**. To take a discount off again, open it and tap **Remove**.

A rep's [role](https://docs.sparklayer.io/help/sales-reps/roles.md) controls the discounts they can give at the counter, as a percentage or a fixed amount.

## Check out

1. Tap **Checkout**.
2. On **Details**, choose the **Shipping Address**, and add a **Purchase Order (PO) Number**, files and a **Preferred Shipping Date** if the customer has them. Tap **Continue**.
3. On **Review & Pay**, choose the **Shipping Method** and **Payment Method**.
4. Check the **Order Summary**, tick **They agree to the terms and conditions**, then tap **Complete Order**.

**More detail**

- **Shipping Address** lists the account's saved addresses; with more than six, use the search above them. Addresses are edited from the customer's account, not the till.
- **Upload Files** takes up to 3 files, each up to 10MB, such as a PDF of their purchase order.
- **Shipping Method** starts on **Collect from the counter** (free), for a customer taking the goods with them. Choose a delivery rate instead to ship it, or **Add custom rate** to enter a description and price. 
- **Discounts & codes** is in the **Order Summary** too, for a last-minute discount.

### Payment methods

| Method | What happens |
| --- | --- |
| **Pay with Net terms** | The order is added to the account's balance and invoiced on their terms. Unavailable when the credit position blocks going on account. |
| **Pay online by card** | The customer is emailed a secure payment link. The order is confirmed once they've paid. |

### Submit a quote instead

1. Tap **Submit Quote** instead of **Checkout**.
2. Complete **Details**, then **Review & Pay** (there's no payment method on a quote). Tap **Continue**.
3. On **Quote Details**, enter a **Quote name**, and optionally **Valid until** and a **Message to the customer**.
4. Tap **Submit Quote**.

**More detail**

Use a quote when the customer wants a price before committing, or when the account can't go on terms. See [Set up quotes](https://docs.sparklayer.io/help/ordering/quoting.md) and [Quotes in Pulse](https://docs.sparklayer.io/help/pulse/quotes.md).

## Finish and serve the next customer

The **Complete** screen confirms what happened: **Put on account**, **Send payment link** or **Save as quote**, with the customer, total, number of lines, delivery or collection, and PO number.

1. Tap **Print receipt** to print a receipt with every line, the subtotal, tax and total.
2. Tap **Next customer** to go back to **Who's buying?**.

## Hold an order

Put an order on hold when a customer steps away or you need to serve someone else.

1. Choose **Actions > Hold this order**. The order is parked and the till is ready for the next customer.
2. To pick it up again, find it under **Held at this counter** on **Who's buying?** and tap **Resume**.

**More detail**

Held orders are kept on the device you held them on, so resume them at the same counter. Each account can have one held order: holding another for the same account replaces it.

## Use it on a tablet or phone

On a smaller screen, the order panel folds away. A bar along the bottom shows the customer, the items and lines in the order, and the total.

1. Tap the bar to open the order as a sheet.
2. Tap outside the sheet to close it.

Everything else works the same, and every control is sized for a finger.

## FAQs

**Can customers use Counter mode?**

No. It's for sales reps only. Customers have [Quick Order](https://docs.sparklayer.io/help/sales-ordering/catalog.md), the same product browser without the **Counter** button.

**Why can't I choose Pay with Net terms?**

The account is over its credit limit with this order, or has an invoice 60 or more days past its terms. Take payment with **Pay online by card**, or submit a quote. Tap the credit position to see the open invoices.

**A scan didn't find the product**

The till says no code matched and searches for what was scanned instead. Check the product's barcode or SKU in your platform matches the code on the label.

**What happens to the order if I tap Exit?**

The till keeps it: open **Counter** again and you're back on the order. To serve someone else in the meantime, put it on hold first with **Actions > Hold this order**.


---

# Sales rep setup

URL: https://docs.sparklayer.io/help/sales-reps

Add a sales agent so a member of your team can order for your B2B customers, choose which customer groups they can see, and change or remove their access.

> **Quick summary**
>
> - To let a member of your team order for your B2B customers, make them a sales agent: go to **Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app and click **Add sales agent**. A sales agent is a customer account in your store with a sales agent role.
> - By default, a sales agent can see every B2B customer. To limit them, tick the **customer groups** they can see on their page. What each role allows is set in [Roles and permissions](https://docs.sparklayer.io/help/sales-reps/roles.md).
> - Sales agents are on the Starter plan and above: Starter includes 1, Growth 2 and Pro 5. The **Your agents** card shows how many you've used, for example "1 of 2 used". See [Plans and limits](#plans-and-limits).

This page is for you, the store owner or admin. Once you've set up your reps, they use [Sales rep ordering](https://docs.sparklayer.io/help/sales-ordering.md) to take orders and [Pulse](https://docs.sparklayer.io/help/pulse.md) to run their accounts.

## How it works

Any customer in your store can be a sales agent: you give their account a sales agent role. When they sign in to your store, they choose one of the customers they look after. They then order on that customer's behalf, at the customer's prices.

How a sales agent is set up:

1. **Give someone the role**: Any customer can be an agent
2. **Choose who they see**: Some customer groups, or every customer
3. **They order for customers**: They sign in on your store and order for the customers they manage

## Before you start

Each sales agent needs:

- **An active customer account** in your store for the person, with an email address and a complete address.
- **Marked as a B2B customer** in your platform, for example tagged `b2b` on Shopify (see below). SparkLayer only uses `b2b` plus one customer group tag, so remove any other B2B-looking tags: they can conflict.
- **Their own login.** Give every agent their own account and email address. Shared logins make [cart locking](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#cart-locking) conflicts more likely.
- **A free sales agent place** on your plan. Check the "used" count on the **Your agents** card at **Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app.

## Add a sales agent

**Shopify:**

1. In your Shopify admin, open the person at **Customers** ([open in the Shopify admin](https://admin.shopify.com/customers)), add the `b2b` tag and save.
2. Go to **Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app and click **Add sales agent**.
3. Choose the **Customer**.
4. Choose a **Role**: **Sales agent** or **Sales administrator**.
5. Click **Add agent**.

**More detail**

- To give someone a [custom role](https://docs.sparklayer.io/help/sales-reps/roles.md), add them first, then change their role on their page (see [Change or remove a sales agent](#change-or-remove-a-sales-agent)).
- You can also give someone a role from their customer page at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app: under **Role**, choose the role and click **Save** in the save bar.
- Make every change to a sales agent, including their role and the customer groups they see, in SparkLayer: changing a sales agent's metafields in Shopify has no effect.

**Wix:**

1. In Wix, set the person up as a contact with a complete address and the `b2b` label, and check they're a **Site Member**.
2. Go to **Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app and click **Add sales agent**.
3. Choose the **Customer** and a **Role**, then click **Add agent**.

**Other platforms:**

1. Add the person to a B2B customer group in your platform: a BigCommerce group whose name starts with `B2B`, a **SparkLayer Role** in WooCommerce, or a Magento customer group prefixed "B2B". See [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md).
2. Go to **Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app and click **Add sales agent**.
3. Choose the **Customer** and a **Role**, then click **Add agent**.

The roles you can choose:

| Role | What it allows |
| --- | --- |
| **Customer** | Can log in and place orders for themselves. With this role, they're not a sales agent. |
| **Sales agent** | Can place orders and manage addresses, shopping lists, and company access on behalf of customers. |
| **Sales administrator** | All sales agent permissions, plus editing order prices and creating new customers. |
| Custom roles | Any [custom role](https://docs.sparklayer.io/help/sales-reps/roles.md#create-a-custom-role) you've created. Choose these on the agent's page. |

## Restrict which customers a sales agent can see

By default, a sales agent can see every B2B customer. To limit them to a territory or a type of customer, tick the [customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md) they look after. They then only see customers in those groups.

1. Go to **Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app and click the agent's name.
2. On the **Role** card, under **Customers this agent can see**, tick the customer groups they should see. **Base** is the base customer group.
3. Click **Save** in the save bar.

To let them see every customer again, untick every group. The **Can see** column on the **Sales agents** screen shows the groups, or **All customers**.

**More detail**

- Each customer's page, at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app, lists the agents who can see them under **Sales agents who can see them**.
- To divide customers between agents, set up customer groups that match how you split them, such as one group per region. See [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md).
- Companies and company locations also have a 
  **Sales agents who look after them**
   setting. See 
  [Companies](https://docs.sparklayer.io/help/customers/companies.md)
  . It works together with the customer groups on the agent's page: both apply.
- Older setups used a **sales agent groups** metafield (`sparklayer.sales_agent_groups`) on each customer, and on BigCommerce the **SparkLayer - Sales Agent Groups** attribute. Sales agent groups still apply, alongside the customer groups on the agent's page. See [Older setups: sales agent groups](#older-setups-sales-agent-groups).

### Older setups: sales agent groups

If your store was set up before agents were limited by customer group, it may use sales agent groups instead. Keep these rules in mind:

- **Sales agent groups only work through the customer metafield** `sparklayer.sales_agent_groups`. Customer tags don't put a customer in a sales agent group.
- **Values can only use letters, numbers and dashes**, for example `uk-north`. Spaces aren't allowed.
- **On Shopify, set the metafield to Limit to preset choices**, or customers can fail to sync. See [Set up the sales agent groups metafield](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#set-up-the-sales-agent-groups-metafield).
- **To set it for many customers at once**, use Shopify's bulk editor or an app such as [Matrixify](https://apps.shopify.com/excel-export-import). See [Fill in metafields many at once](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#import-metafields-in-bulk).

## Sign in as a sales agent

Once you've added an agent and chosen who they see, they're ready to order. Here's what they do on your store:

1. The sales agent signs in to your store with their own account, as a customer would.
2. They open the SparkLayer widget. As a sales agent, they also see a **My Customers** tab.
3. They choose a customer to order for. See [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md).
4. If you use 
   [Pulse](https://docs.sparklayer.io/help/pulse.md)
    (early access), they open it from the 
   **Dashboard**
    tab to plan their day and keep track of their accounts. With Pulse, the widget's tabs are 
   **Dashboard**
   , 
   **Catalog**
    and 
   **Order**
   , with no 
   **My Customers**
    tab. See 
   [Open Pulse](https://docs.sparklayer.io/help/pulse.md#open-pulse)
   .

**More detail**

A sales agent can use the same login on several devices, and act as a different customer on each. Only B2B customers with an email address appear in their search.

## Get notified of customer orders

When a customer places an order themselves, you can email their sales agent using your platform's automations.

**Shopify only:**

On Shopify, use [Shopify Flow](https://apps.shopify.com/flow). A typical flow starts when an order (or draft order) is created. It checks which customer it's for, and sends that customer's sales agent an internal email with the order number. Start from our [sample Shopify Flow template](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/Sales_Agents_-_Email_sales_agent_when_order_placed_by_customer.flow?v=1726494991).

## Change or remove a sales agent

To change what an agent can do, give them a different role. To remove their sales agent access, give them the **Customer** role.

1. Go to **Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app and click the agent's name.
2. Under **Role**, choose a different role, or choose **Customer** to remove sales agent access.
3. Click **Save** in the save bar.

**More detail**

With the **Customer** role, the person keeps their customer account and can still sign in and order for themselves. It also frees up their sales agent place.

## The Sales agents screen

**Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app is where you manage your agents. The **Your agents** card lists everyone with a sales agent role, with **View customers** and **Add sales agent** at the top.

| Part | What it shows / does |
| --- | --- |
| **Used** badge | How many sales agents you have out of your plan's allowance, for example "1 of 2 used". |
| Search | Find an agent by name or email. |
| **Name** | The agent's name. Click it to open the agent's page. |
| **Email** | The email they sign in with. |
| **Role** | **Sales agent**, **Sales administrator** or a custom role. |
| **Can see** | The customer groups the agent is limited to, or **All customers**. |

Under the list, **How agents work** sums up the three steps: give someone the role, choose who they see, and they order for customers.

## The agent's page

Click an agent's name to open their page. It's the same page as a customer's, with what SparkLayer holds for them: **Basic information**, **Financial details**, **Role**, **Company users**, **Addresses** and **Identifiers**. Click **View in Shopify** to open them in your Shopify admin.

You can only change the **Role** card here. Everything else comes from your store.

| Part | What it shows |
| --- | --- |
| **Basic information** | Email, company, customer group, price list override, and **Customer groups they can see**: the groups, or **All customers**. |
| **Role** | The agent's role, and under it **Customers this agent can see**. |

Save changes with **Save** in the save bar.

## Plans and limits

| Plan | Sales agents included |
| --- | --- |
| Basic | None |
| Starter | 1 |
| Growth | 2 |
| Pro | 5 |
| Enterprise | Custom |

The **Your agents** card at **Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app shows how many you've used. When they're all used, **Add sales agent** shows **You've used all your sales agents**. Click **Compare plans** to move to a plan with more, or change an agent's role to **Customer** to free up a place. Extra sales agents are also available for $39 a month each. See [Your plan and usage](https://docs.sparklayer.io/help/dashboard/plan-and-features.md).

On the Basic plan, sales agents and roles are locked:

- Clicking **Sales agents** in the menu opens a window that explains the feature, marked **Included in Starter**. Click **Try Starter free for 14 days** to start a trial, or **Book a 15-min demo**.
- The screen itself shows **Sales agents are on Starter and above**, with **Compare plans** and **See how it works**.
- In the SparkLayer Dashboard, the **Sales agents** menu item has a **Starter** tag.

## The Sales reps section

Sales rep setup is part of the Help Center's **Sales reps** section:

| Part | Who it's for | Use it to |
| --- | --- | --- |
| **Sales rep setup** (this part) | You, as the store owner or admin | Make someone a sales agent, choose which customers they see and what their role lets them do. |
| [Sales rep ordering](https://docs.sparklayer.io/help/sales-ordering.md) | Sales reps | Take an order for a customer in the cart, at a trade counter with Counter mode or from the Catalog. |
| [Pulse](https://docs.sparklayer.io/help/pulse.md) (early access) | Sales reps | Plan the day, follow up and keep track of their accounts. |

## Troubleshooting

**Diagnose: Sales agent having problems?** Check their account, role and the customers they can see.

1. **What’s happening?** Pick the closest match.
   - The agent doesn’t see sales agent mode: go to question 2
   - A customer is missing from the agent’s search: go to question 3
   - The agent sees customers they shouldn’t: go to question 4
   - “The cart is being processed by a sales agent”: go to fix A (Another agent has that customer open)
   - The agent can’t edit prices, add customers or override rules: go to question 5
2. **Does the agent’s own customer record have the `b2b` tag?** A sales agent is a B2B customer account with a sales agent role. Where to look: Customers > select the customer > Tags (Shopify admin).
   - Yes: go to question 6
   - No: go to fix B (Add the `b2b` tag to the agent’s account)
3. **Does the missing customer have the `b2b` tag?** Only B2B customers appear in an agent’s search. Where to look: Customers > select the customer > Tags (Shopify admin).
   - Yes: go to question 7
   - No: go to fix C (Add the `b2b` tag to the customer)
4. **Is the agent limited to some customer groups?** By default an agent sees every B2B customer. Where to look: Sales Agents > Agents (SparkLayer).
   - Yes: go to question 8
   - No, all customers: go to fix D (Limit the agent to their customer groups)
5. **Does the agent’s role include permission for this?** Roles decide what an agent can do beyond placing orders, such as editing prices or adding customers. Where to look: Sales Agents > Roles (SparkLayer).
   - Yes: go to question 9
   - No / not sure: go to fix E (Give the role that permission)
6. **Is the person listed as a sales agent in SparkLayer?** Their role decides what they can do. Where to look: Sales Agents > Agents (SparkLayer).
   - Yes: go to question 10
   - No / not sure: go to fix F (Make them a sales agent)
7. **Is the agent limited to some customer groups?** The Sales agents screen shows the groups each agent can see, or All customers. Where to look: Sales Agents > Agents (SparkLayer).
   - Yes: go to question 11
   - No, all customers: go to fix G (Check the customer has synced)
8. **Does your store still use the older sales agent groups metafield (`sparklayer.sales_agent_groups`)?** Older setups gave customers sales agent group values in a metafield. Customer tags never work for this. Where to look: Customers > select the customer > Metafields (Shopify admin).
   - Yes: go to fix H (Check the customers’ sales agent group values)
   - No: go to fix I (Check the customers’ groups)
9. **Is the agent trying to raise a price?** Agents can edit unit prices on an order, but only downwards.
   - Yes: go to fix J (Prices can only be lowered)
   - No: go to fix K (Everything checks out)
10. **Are they signed in on your store with exactly that email?** A different or mistyped email creates a new retail customer with no sales agent role.
   - Yes: go to fix L (Check your plan includes sales agents)
   - No / not sure: go to fix M (Sign in with the sales agent’s email)
11. **Is the customer in one of those groups?** Check the customer’s group tag against the agent’s groups. Where to look: Customers > select the customer > Tags (Shopify admin).
   - Yes: go to fix G (Check the customer has synced)
   - No: go to fix N (Let the agent see that group)

**Fixes**

- **A. Another agent has that customer open** A customer’s cart is locked to the sales agent acting for them. Another agent, or the same login on another device, sees this message until the first agent stops acting for the customer. Give each person their own sales agent login, as shared logins make this much more likely. See [Ordering for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md).
- **B. Add the `b2b` tag to the agent’s account** Sales agents must be B2B customers in your store before they can be given a sales agent role. Add the tag, then make them a sales agent. Where: Customers > select the customer > Tags (Shopify admin).
- **C. Add the `b2b` tag to the customer** Untagged customers never appear in an agent’s search. Add the tag and save. Where: Customers > select the customer > Tags (Shopify admin).
- **D. Limit the agent to their customer groups** On the agent’s page, tick the customer groups they look after. They then only see customers in those groups. Where: Sales Agents > Agents (SparkLayer). See [Restrict which customers an agent sees](https://docs.sparklayer.io/help/sales-reps.md#restrict-which-customers-a-sales-agent-can-see).
- **E. Give the role that permission** Edit the role, tick the permission and save. It applies straight away to every agent with that role. Where: Sales Agents > Roles (SparkLayer). See [Roles and permissions](https://docs.sparklayer.io/help/sales-reps/roles.md).
- **F. Make them a sales agent** Click Add sales agent, choose the person and give them a role. Where: Sales Agents > Agents (SparkLayer). See [Add a sales agent](https://docs.sparklayer.io/help/sales-reps.md).
- **G. Check the customer has synced** If a tagged customer is in the right group but still missing, they may not have synced. Click Show errors on the sync banner. Where: Customers (SparkLayer).
- **H. Check the customers’ sales agent group values** An agent sees any customer that shares one of their group values. Remove values a customer shouldn’t have. Values can only use letters, numbers and dashes, such as `south-east`, and tags don’t count. Where: Customers > select the customer > Metafields (Shopify admin).
- **I. Check the customers’ groups** The agent sees every customer in the groups ticked for them. Untick groups they shouldn’t see, or move those customers to another group. Where: Sales Agents > Agents (SparkLayer).
- **J. Prices can only be lowered** Agents can lower unit prices on an order, not raise them. To charge more, change the customer’s price list.
- **K. Everything checks out** Your setup looks right, so we'll take it from here. Send us your answers with the agent’s and customer’s email addresses.
- **L. Check your plan includes sales agents** Sales agent ordering is on the Starter plan and above, and extra agents are an add-on. If your plan includes them, send us the agent’s email and we’ll take a look. See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
- **M. Sign in with the sales agent’s email** Ask them to sign out and back in using the exact email that has the sales agent role.
- **N. Let the agent see that group** Tick the customer’s group under the customers this agent can see, or move the customer to one of the agent’s groups. Where: Sales Agents > Agents (SparkLayer).

**I can't see sales agent mode**

Sales agent mode (the **My Customers** tab) only shows when the person is signed in on your store with the exact email address that has the sales agent role. Check the **Email** column at **Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app.

A typo, or signing in with a different email, doesn't sign them in as the agent. On Shopify, it creates a new retail customer with no `b2b` tag, who sees your store as a retail shopper. Sign out and sign in again with the right email.

The agent's own customer record also needs the `b2b` tag, as any B2B customer does. Use `b2b` plus at most one customer group tag: extra B2B-looking tags can conflict.

If the email is right, check these too:

- **SparkLayer is on your published theme.** A theme update can remove it. See [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md).
- **The agent's own customer record is complete**, including an address. A record without one can't sync, so the agent isn't recognised.
- **The person has the sales agent role.** Your plan includes a set number of agent places: to hand ordering over to someone new, remove the old agent first. See [Plans and limits](#plans-and-limits).
- **The session is fresh.** Sign out, or try a private (incognito) window. If the agent was stuck in a sign-in loop, see [Customers sign in but land back on your store signed out](https://docs.sparklayer.io/help/troubleshooting.md#sign-in-loop).

**An agent can't see a customer**

Only B2B customers with an email address appear in an agent's search. If a customer is missing, check they're a B2B customer (on Shopify, tagged `b2b`) and have an email address. If they don't have one, give them a placeholder such as `salesagent123@yourstore.com`.

If the agent is limited to some customer groups, the customer must be in one of them. The agent's page shows **Customer groups they can see**. See [Restrict which customers a sales agent can see](#restrict-which-customers-a-sales-agent-can-see).

On an older setup that uses sales agent groups, the customer's `sparklayer.sales_agent_groups` metafield must match the agent's group. Tags don't count. See [Older setups: sales agent groups](#older-setups-sales-agent-groups).

If the agent can find a customer but can't select them, sign out and back in, or try a private window.

**An agent sees 'You cannot update the cart because it is being processed by a sales agent'**

Another sales agent has the same customer open, so the customer's cart is locked to them. See [Cart locking](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#cart-locking).

## FAQs

**Can a sales agent order for themselves?**

Yes. Their own prices come from their own customer group. See [Order for yourself](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#order-for-yourself).

**Why can't I give someone a custom role in Add sales agent?**

**Add sales agent** offers the two built-in roles. Add the person as a **Sales agent**, then open their page and choose the custom role under **Role**.

**I changed a sales agent's metafield in Shopify and nothing happened**

**Shopify only:**

Sales agents' roles and the customer groups they see are managed in SparkLayer, at **Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app. Changes to their own metafields in Shopify have no effect.

## Next steps

- [Roles and permissions](https://docs.sparklayer.io/help/sales-reps/roles.md): Choose what each sales agent can do, such as changing prices
- [Sales rep ordering](https://docs.sparklayer.io/help/sales-ordering.md): Show your reps how to take an order for a customer
- [Pulse](https://docs.sparklayer.io/help/pulse.md): The rep workspace: who to call, quotes, invoices and account health (early access)


---

# Roles and permissions

URL: https://docs.sparklayer.io/help/sales-reps/roles

Control what each sales agent can do with roles: use the built-in Sales agent and Sales administrator roles, or create custom roles with your own permissions.

> **Quick summary**
>
> - A role is a set of permissions, such as changing quoted prices or creating customers. Give a role to as many sales agents as you need.
> - Manage roles at **Sales Agents > Roles** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/roles)), or **SparkLayer Wholesale > Sales agents > Roles** in the Shopify app, and give one to an agent on their page at **Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app.
> - The built-in **Sales agent** and **Sales administrator** roles can't be changed. Duplicate one, or create a custom role, for anything in between.
> - Roles come with sales agents, on the Starter plan and above. They decide what a rep can do when [ordering for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md).

## How it works

You create a role once and give it to every agent who needs it, instead of setting permissions agent by agent. When you change a role, the change applies straight away to every agent who has it.

How roles control access:

1. **Create a role**: Switch on its permissions at Roles
2. **Give it to agents**: On each agent's page
3. **Agent signs in**: They can only use the tools their role allows

## Built-in roles

Every store has 2 built-in roles. You can't change them, but you can give them to agents as they are:

| Role | Permissions |
| --- | --- |
| **Sales agent** | 5 of 13: **Place orders**, **Create quotes**, **Edit quotes**, **Edit addresses** and **Change default addresses**. For day-to-day ordering. |
| **Sales administrator** | All 13. Everything a sales agent can do, plus changing prices, custom items and shipping, and creating customers. |

For anything in between, create a custom role or duplicate a built-in one.

## Create a custom role

1. Go to **Sales Agents > Roles** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/roles)), or **SparkLayer Wholesale > Sales agents > Roles** in the Shopify app and click **Create role**.
2. Enter a **Role name**, such as "Senior rep". It's shown when you give someone a role.
3. On the **Orders**, **Quotes** and **Customers** cards, switch on each permission the role should have (see [Permissions](#permissions)).
4. Click **Save** in the save bar.

**More detail**

- To start from an existing role, open it and click **Duplicate**. This opens **Create role** with the same permissions, named "(copy)", for example "Sales agent (copy)".
- The built-in roles are read-only. Open one and click **Duplicate** to make a version you can change.
- Role names must be unique.

## Edit a custom role

1. Go to **Sales Agents > Roles** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/roles)), or **SparkLayer Wholesale > Sales agents > Roles** in the Shopify app and click the role's name.
2. Change the **Role name** or switch permissions on or off.
3. Click **Save** in the save bar.

Every agent with the role gets the new permissions straight away.

## Give a role to a sales agent

1. Go to **Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app and click the agent's name.
2. Under **Role**, choose the role.
3. Click **Save** in the save bar.

**Add sales agent** offers only the 2 built-in roles. To give a new agent a custom role, add them first, then change their role on their page. See [Sales rep setup](https://docs.sparklayer.io/help/sales-reps.md).

## Delete a custom role

1. Go to **Sales Agents > Roles** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/roles)), or **SparkLayer Wholesale > Sales agents > Roles** in the Shopify app and click the role's name.
2. Click **More actions**, then **Delete role**.
3. Click **Delete role** to confirm.

Anyone who had the role moves to the built-in **Sales agent** role. The confirmation tells you how many reps this affects.

## Permissions

Each permission is a switch on the role's page, in 3 cards: **Orders**, **Quotes** and **Customers**.

| Card | Permission | What it allows |
| --- | --- | --- |
| Orders | **Place orders** | Check out for a customer through the normal checkout. |
| Orders | **Change quoted prices** | Change the price of items already quoted to a customer. See [Change a unit price](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#change-a-unit-price). |
| Orders | **Add custom items** | Add or change [custom line items](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#add-a-custom-item) on an order. |
| Orders | **Change shipping** | Change the shipping method or cost on an order. See [Set a custom shipping rate](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#set-a-custom-shipping-rate). |
| Orders | **Ignore product rules** | Skip rules like minimum quantities or order increments. See [Override quantity rules](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#override-quantity-rules). |
| Quotes | **Create quotes** | Start a quote from the checkout. |
| Quotes | **Edit quotes** | Change a quote after it's created. |
| Quotes | **Complete quotes** | Finalise a quote once it's approved. |
| Quotes | **Archive quotes** | Archive quotes that are no longer needed. |
| Quotes | **Reassign quotes** | Change which rep looks after a quote. |
| Customers | **Create customers** | Add new customer accounts. See [Add a new customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md#add-a-new-customer). |
| Customers | **Edit addresses** | Update a customer's shipping and billing addresses. |
| Customers | **Change default addresses** | Choose which address is used by default. |

The **Quotes** permissions only apply when [quotes](https://docs.sparklayer.io/help/ordering/quoting.md) are turned on at **Settings > Configurations > Quotes and invoices** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations > Quotes and invoices** in the Shopify app (Pro plan, or the Quoting Engine add-on). Until then, the **Quotes** card says "Quotes are off in Settings, so these don't apply yet."

## The Roles screen

**Sales Agents > Roles** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/roles)), or **SparkLayer Wholesale > Sales agents > Roles** in the Shopify app lists every role on the **Sales rep roles** card, with **Create role** at the top.

| Column | What it shows |
| --- | --- |
| **Role** | The role's name. Click it to open the role. |
| **Type** | **Built in** or **Custom**. |
| **Can do** | How many of the 13 permissions the role has, for example "5 of 13 permissions". |
| **Used by** | How many reps have the role, or "No one". |

## On the Basic plan

Roles come with sales agents, which start on the Starter plan. On the Basic plan, **Sales Agents > Roles** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/roles)), or **SparkLayer Wholesale > Sales agents > Roles** in the Shopify app shows **Roles come with sales agents**. Click **Compare plans** to see the plans, or **See how it works** to learn about sales agents. Starter has a 14-day free trial. See [Plans and limits](https://docs.sparklayer.io/help/sales-reps.md#plans-and-limits).

## Good practice

- **Create roles around job functions**, for example a "Sales rep" role for day-to-day ordering and a "Manager" role with wider access.
- **Only give full access** (the Sales administrator role, or a custom equivalent) to people who need it.
- **Review roles as your team grows**, to check the permissions still match how each role is used.

## FAQs

**Can I edit the built-in roles?**

No. The **Sales agent** and **Sales administrator** roles can't be changed or deleted. Open one and click **Duplicate** to make a custom version you can change.

**Can I give one role to several sales agents?**

Yes. Give the same role to as many agents as you need. **Used by** on the Roles screen shows how many reps have each role.

**What happens when I update a role?**

Every sales agent with that role gets the new permissions straight away.

**What happens to reps when I delete a custom role?**

They move to the built-in **Sales agent** role. You don't need to reassign them first. Check their role afterwards if they need more than the Sales agent permissions.

**Do roles control who reviews quotes?**

Roles control what an agent can do with a quote. Who receives a quote is set in the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md#set-up-your-sales-team-for-quoting).

## Next steps

- [Sales rep setup](https://docs.sparklayer.io/help/sales-reps.md): Add a sales agent and choose which customers they see
- [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md): What reps do with these permissions when they take an order


---

# Platforms

URL: https://docs.sparklayer.io/help/platforms

SparkLayer runs on Shopify, BigCommerce, Wix, WooCommerce and Magento. Choose your platform for installation, setup, limitations and FAQs.

> **Quick summary**
>
> - SparkLayer runs on top of 5 eCommerce platforms: Shopify, BigCommerce, Wix, WooCommerce and Magento. Choose yours below for installation, platform-specific setup, limitations and FAQs.
> - On Shopify, you manage SparkLayer in the **SparkLayer Wholesale** app in your Shopify admin, and on Wix in the SparkLayer app in your Wix dashboard. On every platform, you can use the SparkLayer Dashboard at app.sparklayer.io. They all have the same screens.
> - The rest of the Help Center (pricing, customers, ordering, storefront) works the same on every platform. Pages flag any difference with an **Applies to** label or platform tabs.
> - A few features depend on your platform. [Compare platforms](https://docs.sparklayer.io/help/platforms/compare.md) shows what works where.

## Choose your platform

- [Shopify](https://docs.sparklayer.io/help/platforms/shopify.md): Works with all Shopify plans. The free Basic plan is only on Shopify.
- [BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce.md): Works with BigCommerce Plus, Pro and Enterprise.
- [Wix](https://docs.sparklayer.io/help/platforms/wix.md): Works with Wix Editor and Wix Studio.
- [WooCommerce](https://docs.sparklayer.io/help/platforms/woocommerce.md): Early access. WooCommerce 9+, WordPress 6+ and PHP 8.2+.
- [Magento](https://docs.sparklayer.io/help/platforms/magento.md): Magento 2.4.2+ and PHP 7.4+. Requires the Enterprise plan.

## Where you manage SparkLayer

Where you work in SparkLayer depends on your platform.

| Platform | Where you manage SparkLayer | Where your platform is set |
| --- | --- | --- |
| Shopify | The **SparkLayer Wholesale** app, under **Sales channels** in your Shopify admin. You can also sign in to the SparkLayer Dashboard. | Shopify, automatically |
| BigCommerce, Wix, WooCommerce, Magento | The SparkLayer Dashboard at [app.sparklayer.io](https://app.sparklayer.io) | **Your platform** at **Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app |

The BigCommerce, Wix, WooCommerce and Magento guides give paths in the SparkLayer Dashboard.

## What each platform guide covers

Every platform guide has the same core pages, so you know where to look:

| Page | What it covers |
| --- | --- |
| **Install** | Installing SparkLayer, connecting your store and adding the widgets to your theme |
| **Metafields and data mapping** | Which platform fields SparkLayer reads, such as pack sizes and customer details |
| **FAQs** | Common questions specific to that platform |
| **Limitations** | What works differently, or isn't supported, on that platform |
| **Cancel or uninstall** | Cancelling SparkLayer, what happens to your data, and moving to another store |

Shopify also has guides for Shopify-only features, such as [Companies](https://docs.sparklayer.io/help/platforms/shopify/companies.md), [Markets and currencies](https://docs.sparklayer.io/help/platforms/shopify/markets-and-currencies.md) and the [B2B Dawn theme](https://docs.sparklayer.io/help/platforms/shopify/dawn-theme.md).

## Not on one of these platforms?

A developer can connect SparkLayer to another commerce platform with [Ignite](https://docs.sparklayer.io/ignite.md). You can also use SparkLayer headless with the [JavaScript SDK](https://docs.sparklayer.io/developers.md). To talk through your setup, [contact us](https://docs.sparklayer.io/help/support.md).


---

# Shopify

URL: https://docs.sparklayer.io/help/platforms/shopify
Applies to: Shopify

Add B2B and wholesale ordering to any Shopify plan with the SparkLayer Wholesale app: how it works, how to get set up and what's specific to Shopify.

> **Quick summary**
>
> - The [SparkLayer Wholesale app](https://apps.shopify.com/sparklayer) adds B2B ordering to your existing Shopify store. It sits under **Sales channels** in your Shopify admin, and works on every Shopify plan, from Basic to Shopify Plus.
> - Every SparkLayer plan is available on Shopify, including the free Basic plan, which is Shopify only. See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
> - Your theme stays as it is. Signed-in B2B customers see B2B prices, the B2B cart and their account area. Retail (DTC) customers aren't affected.
> - After you install, the **Setup** checklist takes you through 5 steps. [Get set up on Shopify](#get-set-up) takes you from install to launch.

## Who it's for

These guides are for merchants who sell on Shopify and want to take wholesale (B2B) orders. You can run B2B alongside retail in one store, or set up a separate store just for B2B. To choose, see [Shopify B2B store setup](https://docs.sparklayer.io/help/platforms/shopify/customisations/store-setup.md). To see the B2B experience first, [try our demo](https://docs.sparklayer.io/help/get-started/demo.md).

## How it works

You install **SparkLayer Wholesale** from the Shopify App Store. In your Shopify admin, it's a sales channel under **Sales channels**: click it to open **Home**, and the menu items below it open each area, such as **Setup**, **Pricing** and **Customers**. The same screens are in the SparkLayer Dashboard at [app.sparklayer.io](https://app.sparklayer.io/).

SparkLayer adds a B2B layer over parts of your store: product pricing, the cart and the account area. Customers become B2B customers when you tag them `b2b` in Shopify, or invite them from SparkLayer. Their rules (price lists, payment methods, order limits) come from their [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md). New to price lists and customer groups? [How SparkLayer works](https://docs.sparklayer.io/help/get-started/how-sparklayer-works.md) explains them in a few minutes.

## Get set up on Shopify

Most stores are set up in under 15 minutes. After you install, the **Setup** checklist at **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app takes you through the SparkLayer steps and ticks each one off as you go.

Not sure where to start? Answer 4 quick questions and get [your own setup guide](https://docs.sparklayer.io/help/get-started/setup-guide.md): the guides that apply to your store, in the order you need them.

### Step 1. Install SparkLayer Wholesale

Add the app from the [Shopify App Store](https://apps.shopify.com/sparklayer), choose a plan and check your customer accounts version. See [Install SparkLayer on Shopify](https://docs.sparklayer.io/help/platforms/shopify/install.md).

### Step 2. Create a price list

The prices your B2B customers see: for example 20% off your retail prices, or exact prices uploaded by CSV. Click **Create a price list** on the Setup step. See [Set up a price list](https://docs.sparklayer.io/help/get-started.md#set-up-your-b2b-pricing).

### Step 3. Assign it to a customer group, and add your first buyer

Choose the group's **Price list**, then invite a buyer, or tag a customer `b2b` in your Shopify admin. They see your trade prices when they sign in. See [Assign a price list](https://docs.sparklayer.io/help/get-started.md#set-up-your-customer-groups) and [Add your first buyer](https://docs.sparklayer.io/help/get-started.md#add-your-b2b-customers).

### Step 4. Check your theme, and publish it

On most themes, SparkLayer's blocks are added for you. Click **Review theme setup** to check them, then publish the theme. If something isn't right, our team installs SparkLayer for you, free. See [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md).

### Step 5. Test, then launch

Place a test order as a B2B buyer with **Orders > Place a test order** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Try it out** in the Shopify app. It doesn't count towards your plan. Then invite your customers with the [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md).

> **We can set it up with you**
>
> On every plan, our team installs the storefront widgets for you, free. On a paid plan, an onboarding session can also set up your first price lists with you. Click **Book setup call** at the top of Setup. See [Contact support](https://docs.sparklayer.io/help/support.md).

## What's specific to Shopify

Most of SparkLayer works the same on every platform. These are the parts that work differently on Shopify, or only exist there.

| Topic | What to know |
| --- | --- |
| **Customer tags** | SparkLayer identifies B2B customers by the `b2b` tag on their Shopify customer record, plus a second tag for a customer group other than Base (for example `b2b-vip`). **Invite a buyer** adds both for you. See [Add B2B customers on Shopify](https://docs.sparklayer.io/help/platforms/shopify/invite-customers.md). |
| **Customer accounts** | SparkLayer works with both Legacy and new Shopify customer accounts. New customer accounts need a small extra step. See [Install SparkLayer on Shopify](https://docs.sparklayer.io/help/platforms/shopify/install.md#choose-your-customer-accounts-version). |
| **Orders** | Orders paid by card go through the Shopify checkout. Orders with offline payment methods, such as Pay by Invoice, arrive as Shopify draft orders. See [Shopify payment methods](https://docs.sparklayer.io/help/platforms/shopify/customisations/payment-methods.md). |
| **Shopify Companies** | Optional. SparkLayer works alongside Shopify's B2B companies, and links its draft orders to the right company, contact and location. Your Shopify B2B companies and locations show under **Companies** in SparkLayer, kept in sync both ways, and you can give a company or location its own price lists, payment terms and sales reps. See [Shopify Companies](https://docs.sparklayer.io/help/platforms/shopify/companies.md). |
| **Shopify Markets** | Needed to sell to B2B customers in more than one currency. See [Shopify Markets and currencies](https://docs.sparklayer.io/help/platforms/shopify/markets-and-currencies.md). |
| **B2B theme** | Our B2B version of Shopify's Dawn theme comes with the SparkLayer widgets installed, plus a B2B login page and B2B-only products. See [Shopify B2B Dawn theme](https://docs.sparklayer.io/help/platforms/shopify/dawn-theme.md). |
| **Metafields** | Product, customer and order settings such as pack sizes, RRP and credit limits are stored as Shopify metafields. See [Shopify metafields and data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md). |
| **B2B Catalogs** | A free SparkLayer app, only for Shopify, that controls which products each customer group can see. See [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md). |

## Known limitations

The limitations most stores meet are:

- Shopify discounts can't be used alongside SparkLayer. Use SparkLayer's own [discounts](https://docs.sparklayer.io/help/pricing/discounts.md) instead.
- Every product variant needs a SKU, and each SKU must be unique.
- Duties, prices that include tax, and orders that mix taxable and tax-exempt products need a workaround, often a separate B2B store.

See [Shopify limitations](https://docs.sparklayer.io/help/platforms/shopify/limitations.md) for the full list, including the cart's line item limit.

## Shopify guides

Start with **Install SparkLayer on Shopify** and **Theme setup**, which take you from install to launch. Use the rest as you need them.

- [Install SparkLayer on Shopify](https://docs.sparklayer.io/help/platforms/shopify/install.md): Requirements, installing the app, Setup, Theme setup and your first buyer
- [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md): Check SparkLayer's app blocks on your theme
- [B2B Dawn theme](https://docs.sparklayer.io/help/platforms/shopify/dawn-theme.md): A ready-made B2B theme with the SparkLayer widgets installed
- [Shopify Companies](https://docs.sparklayer.io/help/platforms/shopify/companies.md): How SparkLayer works alongside Shopify Companies
- [Markets and currencies](https://docs.sparklayer.io/help/platforms/shopify/markets-and-currencies.md): B2B pricing in more than one currency
- [Metafields and data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md): Product, customer and order metafields, and how orders map to SparkLayer
- [Limitations](https://docs.sparklayer.io/help/platforms/shopify/limitations.md): What SparkLayer can't do on Shopify, and the workarounds
- [Customisations](https://docs.sparklayer.io/help/platforms/shopify/customisations.md): B2B login and registration, B2B-only content, Shopify Flow, emails and reporting
- [Shopify FAQs](https://docs.sparklayer.io/help/platforms/shopify/faqs.md): Answers to common questions about setup, payments, products and orders
- [Error codes](https://docs.sparklayer.io/help/platforms/shopify/error-codes.md): What each SHOPIFY and PRICING error in the cart means and how to fix it
- [Cancel, uninstall or transfer](https://docs.sparklayer.io/help/platforms/shopify/uninstall.md): Cancel SparkLayer, move it to another store or extend a trial


---

# Install SparkLayer on Shopify

URL: https://docs.sparklayer.io/help/platforms/shopify/install
Applies to: Shopify

Install the SparkLayer Wholesale app on Shopify, work through Setup and Theme setup, then place a test order as a buyer before you go live.

> **Quick summary**
>
> - Install the [SparkLayer Wholesale app](https://apps.shopify.com/sparklayer) from the Shopify App Store. It works on every Shopify plan, from Basic to Shopify Plus, and on every SparkLayer plan, including the free Basic plan.
> - The app sits in your Shopify admin under **Sales channels**. Work through **Setup** (a price list, a customer group and your first buyer), **Theme setup** and **Try it out**. Most stores finish setup in under 15 minutes.
> - SparkLayer sets itself up on your theme automatically. If something isn't right, our team installs it for you, free of charge.

> **We can set this up with you**
>
> On a paid plan, our team can set up SparkLayer on your store with you in a personalised onboarding session. Click **Book setup call** on **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app, or [book an onboarding call](https://meetings-eu1.hubspot.com/sparklayer/onboarding), and we'll walk you through it. On any plan, we'll [install the widgets on your theme](#ask-our-team-to-install-it) for free. Or follow this guide to do it yourself.

## How it works

SparkLayer adds B2B ordering to your existing Shopify store. Your B2B customers sign in, see their B2B prices, place orders and manage their account. Your retail (DTC) customers see your store as it is today.

Getting SparkLayer live on Shopify:

1. **Install**: Add SparkLayer Wholesale from the Shopify App Store
2. **Setup**: A price list, a customer group and your first buyer
3. **Theme setup**: Check SparkLayer is on your theme
4. **Try it out**: Place a test order as a B2B buyer
5. **Launch**: Invite the rest of your buyers

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

## Before you start

Check you have these in place before you install:

- **Customer accounts turned on**, so customers can sign in to your store. In your Shopify admin, go to **Settings > Customer accounts** ([open in the Shopify admin](https://admin.shopify.com/settings/customer_accounts)) and choose a version. SparkLayer works with both Legacy and new customer accounts: see [Choose your customer accounts version](#choose-your-customer-accounts-version).
- **A unique SKU on every product**, so SparkLayer can store B2B prices against it. If you need to add them, see Shopify's [SKU guide](https://help.shopify.com/en/manual/products/details/sku).
- **Your first buyer's email address.** You can add them in Shopify with the `b2b` tag, or tag a customer you already have. Customers you've already tagged `b2b` in Shopify need at least one complete address on their record. See [Add B2B customers on Shopify](https://docs.sparklayer.io/help/platforms/shopify/invite-customers.md).
- **A payment method on test stores.** If you're installing on a test store, turn on an example payment method at **Settings > Payments** ([open in the Shopify admin](https://admin.shopify.com/settings/payments)).

## Install the app and connect your store

1. Open the [SparkLayer Wholesale app](https://apps.shopify.com/sparklayer) in the Shopify App Store and install it on your store. 
2. Choose a SparkLayer plan when Shopify asks. You're billed through Shopify, and every paid plan is free for 14 days. See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
3. SparkLayer opens on **Home**. It's now a sales channel called **SparkLayer Wholesale** in your Shopify admin, and it starts syncing your products and customers. 

If you created your SparkLayer account first, connect your store from the SparkLayer Dashboard instead. 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, select **Shopify** and enter your store's address. Then install the app and choose a plan when Shopify asks.

**The B2B Ordering app pixel**

SparkLayer also adds an app pixel called **B2B Ordering** to **Settings > Customer events** ([open in the Shopify admin](https://admin.shopify.com/settings/customer_events)). It tells SparkLayer when a customer completes a card payment in the Shopify checkout, so their cart is cleared. You don't need to do anything with it.

## Find your way around the app

In your Shopify admin, click **SparkLayer Wholesale** under **Sales channels** to open **Home**. Each menu item opens an area, with that area's pages as tabs. These are the ones you need to get going:

| Menu item | Use it to |
| --- | --- |
| **Home** | See this week's B2B sales and follow the **Get your first wholesale order** card. |
| **Setup** | Work through the 5 setup steps. |
| **Try it out** | Place a test order as a B2B buyer. |

The same screens are also in the SparkLayer Dashboard at [app.sparklayer.io](https://app.sparklayer.io/).

## Work through Setup

Setup is the checklist that gets you selling. Use it to do each step yourself. Go to **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app: it has 5 steps in 2 groups, and each step ticks itself off when it's done.

[Get started](https://docs.sparklayer.io/help/get-started.md#work-through-the-steps) walks through every step. On Shopify, these details also apply.

### Set up a price list

An **Automatic** price list works from your Shopify prices, for example 50% off your Shopify retail price or 40% off your compare-at price. A **Manual** price list takes exact prices from a CSV file. See [Managing pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md).

### Assign a price list to a customer group

Each customer group has a Shopify tag, shown under its name, such as `b2b-trade`. A customer joins the group when their Shopify record has the `b2b` tag and the group's tag. Customers with only `b2b` get the **Base customer group**. See [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md).

### Add your first buyer

When you invite a buyer from step 3, SparkLayer adds them to Shopify with the group's tag, and Shopify emails them an invite to your store. They sign in with a one-time code, with no password. See [Invite a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md).

To add the buyer yourself, create them in your Shopify admin as a new customer with the `b2b` tag. See [Add a new customer from scratch](https://docs.sparklayer.io/help/platforms/shopify/invite-customers.md#add-a-new-customer).

### Tag existing customers in Shopify

Customers already in Shopify become B2B customers through their tags. Check each one has:

- **The `b2b` tag** on their Shopify customer record.
- **Their group's tag**, if they belong to a group other than Base: for example `b2b` and `b2b-vip`.
- **No more than 2 B2B tags.** `b2b` with `b2b-vip` is correct; `b2b` with `b2b-vip` and `b2b-user` is not.
- **At least one complete address** on their Shopify record, so they can get through checkout.

To add a tag, open the customer in Shopify and type it in the **Tags** field. If the tag doesn't exist yet, Shopify creates it. To tag many customers at once, see [Add B2B customers on Shopify](https://docs.sparklayer.io/help/platforms/shopify/invite-customers.md#tag-existing-customers). Customers that don't sync show in a banner at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app: click **Show errors** to see why.

If you use Shopify's B2B companies, see [Shopify Companies](https://docs.sparklayer.io/help/platforms/shopify/companies.md) for how they work with SparkLayer.

## Add SparkLayer to your theme

With your prices and buyers ready, check SparkLayer is on your theme. The SparkLayer frontend is a set of B2B widgets that sit over parts of your Shopify store: the cart and account area, the product page and the product cards on collection pages. They only appear for signed-in B2B customers, so your retail store is untouched.

When you install the app, SparkLayer sets itself up on your theme automatically. Steps 4 and 5 of Setup, **Add SparkLayer to your theme** and **Publish theme**, check it for the theme you choose under **Select theme**. You don't have to edit any theme code yourself. To check each SparkLayer block is on, click **Review theme setup** on step 4: [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md) explains every block, and the 3 ways to install SparkLayer on your theme.

### Ask our team to install it

If you'd rather not touch your theme, or something doesn't look right, our team installs SparkLayer for you, free of charge, on every plan. Click **Something not right? Install SparkLayer for me** on Theme setup, or **Request installation** at **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app. See [Ask our team to install it](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md#get-our-team-to-install-it) for what happens next and what the installation includes.

### Match your store's design

Optionally, style the widgets to match your store: button colours, font sizes, spacing and typefaces. This is a CSS change for you or your developer. Add the CSS snippet from [Change your brand colours and fonts](https://docs.sparklayer.io/help/storefront/customising-design.md#add-custom-css-to-your-store) to `theme.liquid` or a separate CSS file. If [our team installed SparkLayer](#ask-our-team-to-install-it), we match your branding for you.

### Use the B2B Dawn theme instead

If you'd rather not change your existing theme, our [B2B Dawn theme](https://docs.sparklayer.io/help/platforms/shopify/dawn-theme.md) comes with all the SparkLayer widgets installed.

### Automatic install on supported themes

SparkLayer works on any Shopify theme. On the themes below, the product detail and product card interfaces are added automatically as app blocks. You don't need the theme code in steps 2 and 3 of [Install the widgets yourself](#install-the-widgets-yourself).

- **Dawn family:** Dawn, Refresh, Sense, Studio, Craft, Taste, Origin, Ride, Colorblock, Crave, Spotlight, Publisher, Trade
- **Horizon family:** Horizon
- **Archetype family:** Impulse, Expanse, Streamline
- **Other:** Savor, Ritual, Vessel, Atelier, Dwell, Pitch, Heritage, Tinker

On these themes, the automatic install also applies a small amount of CSS, so the B2B widgets sit cleanly alongside your theme. If that causes styling conflicts, your developer can [turn off the automatic install](#turn-off-the-automatic-install) and add the interfaces by hand.

### Install the widgets yourself

This section is for you or your developer, if you want to place the widgets by hand. Step 1 takes a couple of clicks. Steps 2 and 3 can be done with the optional blocks on Theme setup, or as theme code changes. Skip the code on a [supported theme](#automatic-install-on-supported-themes), or [ask our team](#ask-our-team-to-install-it) and we do it free of charge.

> **Work on a copy of your theme**
>
> Duplicate your live Shopify theme and make the changes on the copy. Choose the copy under **Select theme** on Setup to check it, then publish it when you're happy with it.

**Step 1.** **Turn on the SparkLayer block**

The **SparkLayer** block loads SparkLayer's JavaScript on your storefront, with the cart and account area. On **Home > Setup > Theme setup** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Setup > Theme setup** in the Shopify app, check it shows **Enabled**. If it doesn't, click **Edit** to open your theme editor at the block. Turn it on and click **Save**.

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

The [product detail interface](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) replaces your product page's buying area with B2B prices and quantity controls when a B2B customer is signed in.

The quickest way is the **Product block**: on Theme setup, click **Add** beside it, place it in the theme editor and click **Save**. To add it in theme code instead, add this snippet to the file that controls your product page. That's usually `main-product.liquid` or `product-template.liquid` in your theme's `/sections/` folder:

```liquid
<spark-pdp parent-id="{{ product.id }}"></spark-pdp>
```

If your theme has a `{% when 'price' %}` block, add the snippet directly beneath it:

```liquid
{% when 'price' %}<spark-pdp parent-id="{{ product.id }}"></spark-pdp>
```

If you're adding SparkLayer to your existing retail theme, hide the elements B2B customers shouldn't see, such as retail prices, quantity selectors, product options and buy buttons. To hide an element, add `data-spark="b2c-only"` to it:

```html
<div data-spark="b2c-only" class="product-meta-reference">
```

The [frontend integration checklist](https://docs.sparklayer.io/developers/frontend.md#frontend-integration-checklist) lists every element to hide.

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

The [product card interface](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) adds B2B prices and quantity controls to your collection pages, so customers can add items to their order from anywhere in your store.

The quickest way is the **Product card block**: on Theme setup, click **Add** beside it, place it in the theme editor and click **Save**. To add it in theme code instead, find the file that renders product cards on collection pages. That's usually `card-product.liquid`, `product-grid-item.liquid` or similar in your theme's `/snippets/` folder. Look for the line that renders the product title:

```liquid
{{ product.title }}
```

Add this snippet directly below it:

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

Depending on your theme, `product.id` may need to be `card_product.id` or similar: check how your theme names the variable. As with the product page, hide any retail elements with `data-spark="b2c-only"`.

When the widgets are in place, use [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order) to check your product pages and collection pages as a B2B customer. Your developer can use the [frontend integration checklist](https://docs.sparklayer.io/developers/frontend.md#frontend-integration-checklist) to check everything is configured correctly.

### Turn off the automatic install

This is for developers. Turn off the automatic install to control exactly where the interfaces appear on a [supported theme](#automatic-install-on-supported-themes), or to avoid the automatic styling. Add this to your theme's `theme.liquid` file, just before the closing `</head>` tag:

```html
<script>
  window.sparkShopify = {
    options: {
      disableAutoInstall: true
    }
  };
</script>
```

Then follow steps 2 and 3 of [Install the widgets yourself](#install-the-widgets-yourself) to add the interfaces where you want them.

## Choose your customer accounts version

B2B customers sign in to your store with a Shopify customer account, so customer accounts must be turned on. Shopify offers 2 versions:

- **Legacy** (formerly "classic"): customers create an account and sign in with an email and password. Most Shopify stores use this version. It works with third-party apps, and you can customise how it looks.
- **Customer accounts** (often called "new customer accounts"): customers sign in with a one-time code sent to their email, with no password. The account area is Shopify's own, much like the checkout, and can't be restyled.

| Version | Advantages | Disadvantages |
| --- | --- | --- |
| **Legacy** | A smoother customer experience. No extra setup. | Functionality is specific to your Shopify store. Not fully supported by Shopify. |
| **Customer accounts (new)** | Works on all Shopify stores. Actively maintained by Shopify. | Limited customisation (for example, you can't change the look and feel). Customers sign in with a 6-digit code rather than a password. |

To check or change your version:

1. In your Shopify admin, go to **Settings > Customer accounts** ([open in the Shopify admin](https://admin.shopify.com/settings/customer_accounts)).
2. Make sure **Show login links** is on, so the sign-in link shows in your store's header and at checkout.
3. Under **Choose which version of customer accounts to link to**, select **Customer accounts** or **Legacy**, then save.

If you use Legacy accounts, there's nothing more to do. If you use new customer accounts, follow [Set up new customer accounts](#set-up-new-customer-accounts) below.

With new customer accounts, anyone can sign in with an emailed code and get a Shopify customer account, without applying. On a wholesale-only store, see [Wholesale-only stores](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md#wholesale-only-stores-customers-who-sign-in-without-a-trade-account) for how to handle them.

### Set up new customer accounts

New customer accounts need 2 changes. Make both: without the second, some customers get stuck in a sign-in loop.

**Step 1.** **Turn on the B2B Account Redirect extension**

When a B2B customer opens Shopify's customer account area, this extension sends them back to your online store, where they can use SparkLayer.

1. In your Shopify admin, go to **Settings > Checkout** ([open in the Shopify admin](https://admin.shopify.com/settings/checkout)).
2. Under **Configurations**, click **Customize** beside your live configuration.
3. From the page selector at the top, open the **Orders** page.
4. Click **Apps** on the left, then turn on the **B2B Account Redirect** extension.
5. Optionally, fill in the extension's **Block settings**:
   - **Redirect Notice (Optional)**: a message shown before the customer is redirected. If you leave it blank, customers see "Please note, you are being redirected to our website to begin your B2B ordering."
   - **Redirect Path (Optional)**: where to send the customer, for example `/collections/all`. If you leave it blank, they go to your homepage.
6. Click **Save**.

You only need to do this once. It applies to every page in the Shopify customer account area. [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md) lists the redirect as a required block, **B2B Account Redirect**, so you can check it's on there.

**Step 2.** **Update your theme's sign-in links (for your developer)**

With a small theme code change, customers return to your store, and the page they were on, after signing in. Without it, some customers are sent back to your store still signed out, again and again. A theme update or redesign can replace these links, so check them again after any theme change. If you don't edit theme code yourself, pass the detail below to your developer or [contact our support team](https://docs.sparklayer.io/help/support.md) and we'll make the change.

**Theme code for your developer**

Shopify's [technical guide to customer account links](https://shopify.dev/docs/storefronts/themes/login) explains the routes used here.

1. In your theme code, find the Liquid code for the account link: usually the person icon in your store's header.
2. Update the link destination as in the sample below.

```html
{%- if shop.customer_accounts_enabled -%}
  <a href="{%- if customer -%}{{ routes.account_url }}{%- else -%}{{ routes.storefront_login_url }}{%- endif -%}"
    class="icon"
    rel="nofollow">
  </a>
{%- endif -%}
```

You can use the same route on any link in your store:

```html
<a href="{%- if customer -%}{{ routes.account_url }}{%- else -%}/customer_authentication/login?return_to={{ request.path | append: "#spark-account" | url_encode }}{%- endif -%}">
Login
</a>
```

If you need help with either step, [contact our support team](https://docs.sparklayer.io/help/support.md).

## Try it out as a buyer

Before you invite anyone, see SparkLayer the way your buyers will.

1. Go to **Orders > Place a test order** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Try it out** in the Shopify app and choose the theme.
2. Work through **Test as a B2B customer**, **Assign a price list** and **Place a test order**.

SparkLayer creates a test customer with the `b2b` tag for you, and the test order doesn't count towards your plan. See [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order).

## Test and launch

When Setup shows **You're ready to go with SparkLayer** and your test order looks right, work through the [launch checklist](https://docs.sparklayer.io/help/get-started/launching.md). It covers the remaining checks, such as products in the **SparkLayer Wholesale** sales channel, and inviting the rest of your buyers.

To go live, click **Start taking B2B orders** on the app's **Home**. A **preview mode** banner on your store means this step isn't done yet. See [Turn off preview mode](https://docs.sparklayer.io/help/get-started/launching.md#turn-off-preview-mode).

## Troubleshooting

**Diagnose: SparkLayer not showing or looking wrong?** Find out whether it’s the customer, your theme or the launch step.

1. **What’s happening?** Pick the closest match.
   - SparkLayer isn’t showing at all: go to question 2
   - There’s a “preview mode” banner on my store: go to fix A (Finish the last launch step)
   - It looks broken, doubled up or unstyled: go to question 3
   - Prices or buttons are missing on some products: go to fix B (This is usually the product, not your theme)
2. **Is it happening for every B2B customer, or just one?** Sign in as another B2B customer to compare, or use Place a test order, which opens your store as a test B2B customer. Where to look: Orders > Place a test order (SparkLayer).
   - Every B2B customer: go to question 4
   - Just one customer: go to question 5
3. **What looks wrong?** Sign in as a B2B customer and compare with a retail visitor.
   - Two carts or two account icons: go to fix C (Your theme’s own cart is still showing)
   - Colours or styles stopped working after publishing a theme: go to fix D (Check SparkLayer isn’t loaded twice)
   - Retail elements show to B2B customers: go to fix E (Hide the retail element for B2B customers)
   - The cart count in my header is wrong: go to fix F (The SparkLayer cart is separate from your theme’s cart)
   - A button or feature is missing, such as shopping lists: go to fix G (Your theme may have an older version of SparkLayer)
   - It broke after a theme change: go to fix H (Add SparkLayer to your new theme)
   - Something else: go to fix I (We’ll need to look at your theme)
4. **Have you changed, updated or duplicated your live theme recently?** SparkLayer is added to a theme, so a new or updated theme won’t include it until it’s added there too. Where to look: Online Store > Themes (Shopify admin).
   - Yes: go to fix H (Add SparkLayer to your new theme)
   - No: go to question 6
5. **Are you checking while signed in as that customer?** SparkLayer only appears once a B2B customer signs in. Retail and signed-out visitors see your store as normal.
   - Yes: go to question 7
   - No / not sure: go to fix J (Sign in as the customer first)
6. **Does Theme setup show SparkLayer’s required blocks turned on for your live theme?** Theme setup checks the app blocks on your theme and lets you turn on any that are off. Where to look: Home > Setup > Theme setup (SparkLayer).
   - Yes: go to question 8
   - No / not sure: go to fix K (Turn on SparkLayer’s blocks)
7. **Does the customer have the `b2b` tag?** Check the spelling exactly, with no extra spaces or characters. Where to look: Customers > select the customer > Tags (Shopify admin).
   - Yes: go to question 9
   - No: go to fix L (Add the `b2b` tag)
8. **Did it stop suddenly, for everyone, without any change on your side?** For example, B2B customers are signed out straight after signing in, or see a blank page.
   - Yes: go to fix M (This may be on our side)
   - No: go to fix I (We’ll need to look at your theme)
9. **Are they signing in with the same email as that customer record?** Signing in with a different or mistyped email creates a new retail customer without the tag.
   - Yes: go to fix N (Check the customer has synced)
   - No / not sure: go to fix O (Sign in with the email on the customer record)

**Fixes**

- **A. Finish the last launch step** The banner means SparkLayer is still in preview. In your Shopify admin, open SparkLayer Wholesale under Sales channels and click Start taking B2B orders. If the button isn’t there, a setup step such as adding SparkLayer to your theme isn’t complete yet. Finish it, or ask us to check: we may ask for collaborator access with the Apps and channels permission. Where: Sales channels > SparkLayer Wholesale (Shopify admin). See [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md).
- **B. This is usually the product, not your theme** When SparkLayer shows but some products have no price or buttons, the cause is usually the product’s SKU, sales channel or price list. Next: Product missing, no B2B price or “Unavailable”?
- **C. Your theme’s own cart is still showing** SparkLayer replaces the cart and account links for signed-in B2B customers. If both show, your theme’s header hasn’t been set up for SparkLayer, which is common after a theme update. Send us the theme name and we’ll fix it.
- **D. Check SparkLayer isn’t loaded twice** If SparkLayer is added by the app embed and also by a copy of its script in the theme code, the second copy can override your styles. Keep the app embed and remove the hard-coded script. CSS variables start with two hyphens, for example `--spark-button-color`. Where: Online Store > Themes (Shopify admin). See [Customise the design](https://docs.sparklayer.io/help/storefront/customising-design.md).
- **E. Hide the retail element for B2B customers** Theme or app elements meant for retail shoppers need hiding when a B2B customer signs in, usually after adding a new app or section. Send us a screenshot and the page link and we’ll hide it, or hide it yourself with B2B-only content. See [B2B-only content](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-only-content.md).
- **F. The SparkLayer cart is separate from your theme’s cart** Your header’s cart count reads Shopify’s cart, so for B2B customers it shows 0 or items added before they signed in. Hide the count for B2B customers, or have a developer keep it in step with SparkLayer’s cart using the JavaScript SDK. We can hide it for you. See [JavaScript SDK: cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md).
- **G. Your theme may have an older version of SparkLayer** Newer features need a recent version of SparkLayer’s storefront code on your theme. Tell us which feature is missing and the theme name, and we’ll update it.
- **H. Add SparkLayer to your new theme** Your new or updated theme doesn’t include SparkLayer yet. Turn on its blocks in Theme setup, or ask us to install it for you, free. Ideally do this before you publish the theme, so B2B customers aren’t affected. Where: Home > Setup > Theme setup (SparkLayer). See [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md).
- **I. We’ll need to look at your theme** Your setup looks right, so we'll take it from here. Send us your answers with a link to your store and the theme name.
- **J. Sign in as the customer first** SparkLayer only appears for signed-in B2B customers. Sign in as them, or use Place a test order to open your store as a test B2B customer, and check again. Where: Orders > Place a test order (SparkLayer).
- **K. Turn on SparkLayer’s blocks** Without them SparkLayer can’t load for anyone. Turn on any required block that’s off. If one won’t turn on, ask us to install SparkLayer on your theme, free. Where: Home > Setup > Theme setup (SparkLayer). See [Ask our team to install it](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md#get-our-team-to-install-it).
- **L. Add the `b2b` tag** Without it the customer shops as retail and sees none of SparkLayer. Add the tag, save, then ask them to sign out and back in. Where: Customers > select the customer > Tags (Shopify admin).
- **M. This may be on our side** If nothing changed on your store, ask your customers to sign out and back in (clearing cookies helps), then tell us straight away. A sync error on one customer never signs out everyone.
- **N. Check the customer has synced** Their tag is right, so check SparkLayer has their record. Click Show errors on the sync banner. A missing or incomplete address stops a customer syncing: every address in their Shopify address book needs a country, city, address line 1 and postcode. An “Invalid customer group” error means a tag doesn’t match any customer group. Where: Customers (SparkLayer). See [Fix customers that won’t sync](https://docs.sparklayer.io/help/guides/fix-sync-problems.md).
- **O. Sign in with the email on the customer record** A different or mistyped email creates a separate retail customer with no tags. Sign in with the exact email that has the `b2b` tag. You can delete the extra customer in Shopify. Where: Customers > select the customer > Tags (Shopify admin).

**My store shows a preview mode banner**

The final launch step isn't done. In your Shopify admin, open **SparkLayer Wholesale** under **Sales channels** and click **Start taking B2B orders** on **Home**. If the button isn't there, the app thinks a setup step isn't complete, such as **Add SparkLayer to your theme**: check **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app. If every step looks done, [contact us](https://docs.sparklayer.io/help/support.md). We may need collaborator access to your store with the **Apps and channels** permission. See [Turn off preview mode](https://docs.sparklayer.io/help/get-started/launching.md#turn-off-preview-mode).

**Someone signed in without a trade account and sees retail prices**

With new customer accounts, anyone can sign in with an emailed code. SparkLayer only loads for customers tagged `b2b`, so they see your store as a retail shopper. See [Wholesale-only stores](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md#wholesale-only-stores-customers-who-sign-in-without-a-trade-account).

For other problems, such as pricing, see [Troubleshooting](https://docs.sparklayer.io/help/troubleshooting.md), or [contact our support team](https://docs.sparklayer.io/help/support.md).

## Recommended next steps

Once SparkLayer is live, optional extras improve the B2B experience, such as a B2B login and registration page, B2B-only products, pack sizes and B2B shipping. See [Turn on extra B2B features](https://docs.sparklayer.io/help/get-started/launching.md#turn-on-extra-b2b-features) and [Shopify customisations](https://docs.sparklayer.io/help/platforms/shopify/customisations.md). For every storefront option, see [Storefront](https://docs.sparklayer.io/help/storefront.md).

Answers to common questions about plans, setup, payments, products and orders are in [Shopify FAQs](https://docs.sparklayer.io/help/platforms/shopify/faqs.md).

- [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md): Check SparkLayer's blocks on your theme, or ask our team to install it
- [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md): The final checks, then invite your B2B customers


---

# Theme setup

URL: https://docs.sparklayer.io/help/platforms/shopify/theme-setup
Applies to: Shopify

Check SparkLayer's app blocks on your Shopify theme in Theme setup, add the optional product blocks, or ask our team to install SparkLayer for you, free.

> **Quick summary**
>
> - **Theme setup** shows whether SparkLayer is installed on your Shopify theme, block by block. Find it at **Home > Setup > Theme setup** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Setup > Theme setup** in the Shopify app.
> - Two blocks are required: **SparkLayer** (the cart and account) and **B2B Account Redirect**. Two are optional: **Product block** and **Product card block**.
> - **Edit** or **Add** opens Shopify's theme editor at that block, with no code to write.
> - If something isn't right, click **Something not right? Install SparkLayer for me**. Our team installs SparkLayer on your theme for you, free.

## How it works

SparkLayer adds its storefront widgets to your Shopify theme as app blocks: small pieces you turn on and position in Shopify's theme editor, without editing theme code. When you install the **SparkLayer Wholesale** app, SparkLayer sets up B2B on your theme automatically, so your B2B customers see it as soon as they sign in. Retail customers don't see any of it.

Theme setup is where you check that setup and change it. It's step 4 of Setup, after your price list, customer group and first buyer.

To get there, click **Review theme setup** on step 4 of **Setup**, or **Open theme setup** on the **Store status** card on **Home**.

## Check SparkLayer is on your theme

1. Go to **Home > Setup > Theme setup** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Setup > Theme setup** in the Shopify app.
2. Check the status says **Complete**. If it does, SparkLayer is installed, and your B2B customers see it when they sign in.
3. Under **App blocks**, check both required blocks show **Enabled**.

If a required block isn't on, [turn it on](#edit-or-add-a-block), or [ask our team to install it](#get-our-team-to-install-it) for you.

Theme setup controls where SparkLayer's widgets sit on your theme. For what you can change inside them, such as colours, labels and which fields show, see [What you can and can't change on the storefront](https://docs.sparklayer.io/help/storefront/what-you-can-change.md).

### What each block does

| Block | Needed? | What it does |
| --- | --- | --- |
| **SparkLayer** | Yes | Adds the B2B cart and account to your store. |
| **B2B Account Redirect** | Yes | Sends B2B customers back to your storefront after they sign in, where SparkLayer runs. |
| **Product block** | Optional | Lets you choose where B2B prices and quantity controls sit on product pages. |
| **Product card block** | Optional | Lets you choose where B2B prices show on product cards in collections. |

If you use Shopify's new customer accounts, the **B2B Account Redirect** needs turning on: see [Set up new customer accounts](https://docs.sparklayer.io/help/platforms/shopify/install.md#set-up-new-customer-accounts). 

## Edit or add a block

Use **Edit** or **Add** to turn a block on, or to change where it sits on the page.

1. Go to **Home > Setup > Theme setup** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Setup > Theme setup** in the Shopify app.
2. In **App blocks**, click **Edit** beside a block that's on, or **Add** beside an optional block. Shopify's theme editor opens at that block.
3. Make your change, such as turning the block on or moving it on the page, then click **Save** in the theme editor.
4. Go back to Theme setup to check the block's status.

**When to add the optional blocks**

The **Product block** puts B2B prices and quantity controls on your product pages, and the **Product card block** puts B2B prices on the product cards in your collections. Add them to choose exactly where SparkLayer shows on those pages. On some themes SparkLayer adds these interfaces for you: see [Automatic install on supported themes](https://docs.sparklayer.io/help/platforms/shopify/install.md#automatic-install-on-supported-themes).

## Ways to install SparkLayer on your theme

Theme setup uses the recommended app embed. **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app lists all 3 ways to add SparkLayer to your theme:

| Way | Best for | Button |
| --- | --- | --- |
| **App embed** (Recommended) | Most stores. SparkLayer's app blocks, turned on in your theme, with no code. | **Open theme setup** |
| **Ask us to install it** | Anyone who'd rather not touch their theme. Our team installs SparkLayer for you, free. | **Request installation** |
| **Manually** | Developers, and heavily customised themes. Add the core script to `theme.liquid`. | **Installation guide** |

For the manual route, see [Install the widgets yourself](https://docs.sparklayer.io/help/platforms/shopify/install.md#install-the-widgets-yourself) and the [frontend integration guide](https://docs.sparklayer.io/developers/frontend.md). If you'd rather not change your existing theme at all, the [B2B Dawn theme](https://docs.sparklayer.io/help/platforms/shopify/dawn-theme.md) comes with every SparkLayer widget installed.

## Ask our team to install it

If you'd rather not touch your theme, a block won't turn on, or SparkLayer doesn't look right on your store, our team installs it on your theme for you, free of charge, on every plan.

1. On Theme setup, click **Something not right? Install SparkLayer for me**, or at **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app, click **Request installation** under **Ask us to install it**.
2. Our onboarding team is notified and gets in touch, usually within a working day.
3. We ask for collaborator access to your Shopify store, which you approve in your Shopify admin. 

As part of the install, we:

- Add the storefront widgets for the product page and product cards.
- Match your store's branding (colours and fonts).
- Add a B2B login and application page.
- Check that everything is set up correctly.

On a paid plan, we then walk you through it all in a personalised onboarding session. See [Contact support](https://docs.sparklayer.io/help/support.md).

## FAQs

**Theme setup says Complete, but I can't see SparkLayer on my store**

SparkLayer only shows to signed-in B2B customers. Retail and signed-out visitors see your store as normal. To see it, use [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order), which opens your store signed in as a test B2B customer, or click **Preview storefront** on Home's **Store status** card.

**Which theme does Theme setup check?**

The theme chosen in **Select theme** on **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app, which starts on your published theme (marked **Active**). Choose another theme there, such as a copy you're working on, to check it before you publish it.

**I've changed or updated my theme. Do I need to set SparkLayer up again?**

Not always, but check Theme setup for the new theme. App blocks you turned on in the old theme aren't always carried across, and a theme update can remove changes made to theme code. If anything's missing, turn it on again with **Edit** or **Add**, or click **Something not right? Install SparkLayer for me**. When we reinstall SparkLayer on an updated theme, we don't copy your own theme edits across, so keep a copy of them.

## Next steps

- [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md): Test your setup, invite your first customers and go live
- [Invite a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md): Send your first trade customer an invite
- [Install SparkLayer on Shopify](https://docs.sparklayer.io/help/platforms/shopify/install.md): The full install, from the app to your first buyer
- [Storefront widgets](https://docs.sparklayer.io/help/storefront/interfaces.md): What the B2B widgets do on your store


---

# Add B2B customers on Shopify

URL: https://docs.sparklayer.io/help/platforms/shopify/invite-customers

Make a customer a B2B customer on Shopify: tag customers you already have, or add a new one from scratch, so they see your trade prices when they sign in.

> **Quick summary**
>
> - A Shopify customer becomes a B2B customer when their customer record has the `b2b` tag. When they sign in to your store, SparkLayer shows them your trade prices.
> - **Customers you already have:** add the `b2b` tag in your Shopify admin, one at a time or many at once.
> - **New customers:** add them in your Shopify admin with the `b2b` tag, then let them know they can sign in.
> - Every B2B customer needs at least one complete address on their Shopify record, so they can get through checkout.

## How it works

SparkLayer reads your Shopify **customer tags**. A customer with the `b2b` tag gets your Base customer group's prices and rules. To put them in another [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md), give them that group's tag as well, such as `b2b-trade`.

From Shopify customer to B2B customer:

1. **Tag them**: Add `b2b` (and their group's tag) to the customer in Shopify
2. **They sign in**: They sign in to your store with their email
3. **They see trade prices**: SparkLayer loads with their group's prices and rules

Find each group's tag under its name at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app, for example "Tag: b2b-trade".

- **The `b2b` tag** on every B2B customer, even if they're also in another group.
- **Their group's tag as well**, if they belong to a group other than Base, for example `b2b` and `b2b-trade`.
- **No more than 2 B2B tags.** `b2b` with `b2b-trade` is correct; `b2b` with `b2b-trade` and `b2b-vip` is not.
- **At least one complete address** on their Shopify record.

## Add a customer you already have

If the customer already has an account on your store, tag them:

1. In your Shopify admin, go to **Customers** ([open in the Shopify admin](https://admin.shopify.com/customers)) and open the customer.
2. In the **Tags** box, type `b2b` and choose it, or add it as a new tag.
3. To put them in another group, add its tag too, for example `b2b-trade`.
4. Check they have a complete address, then click **Save**.

The next time they sign in to your store, they see your trade prices.

### Tag many customers at once

1. At **Customers** ([open in the Shopify admin](https://admin.shopify.com/customers)), tick the customers you want.
2. Click **More actions** > **Add tags**, enter `b2b` (and a group tag, if you use one) and click **Save**.

For a long list, you can also import a customer CSV with a **Tags** column in your Shopify admin. See Shopify's [customer import guide](https://help.shopify.com/en/manual/customers/import-export-customers).

## Add a new customer from scratch

To set up a customer who doesn't have an account on your store yet:

1. In your Shopify admin, go to **Customers > Add customer** ([open in the Shopify admin](https://admin.shopify.com/customers/new)).
2. Enter their **First name**, **Last name** and **Email**.
3. Add their address, including the company name if they have one.
4. Under **Tags**, add `b2b`, and their group's tag if they're in another group.
5. Click **Save**.
6. Let them know they can sign in. How depends on your [customer accounts version](https://docs.sparklayer.io/help/platforms/shopify/install.md#choose-your-customer-accounts-version):
   - **New customer accounts:** there's nothing to send from Shopify. They sign in on your store with their email and a one-time code. Send them a link to your store's sign-in page.
   - **Legacy customer accounts:** on the customer's page, click **Send account invite**. Shopify emails them a link to set a password.

Coming soon, you can [invite a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md) from SparkLayer instead. SparkLayer adds them to Shopify with the right tags and emails them the invite.

## Let customers apply themselves

Rather than adding each customer yourself, you can let them apply for a trade account. A registration form collects their details, and you approve them by adding the tags. See [B2B registration and login](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md).

## Check it works

Sign in to your store as the customer, or use [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order), which signs you in as a test B2B customer. You should see your trade prices and the SparkLayer cart.

## Troubleshooting

**The customer signs in but sees retail prices**

Check their Shopify record has the `b2b` tag, spelt exactly, and no more than 2 B2B tags. Then check SparkLayer is on your theme: see [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md).

**The customer isn't in SparkLayer**

Customers that don't sync show in a banner at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app. Click **Show errors** to see why. A missing address is the most common reason.

**The customer can't get through checkout**

Add a complete address to their Shopify record.

## Next steps

- [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md): Give groups of customers their own prices, payment methods and rules
- [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md): Test as a B2B customer, invite your first customers and go live


---

# B2B Dawn theme

URL: https://docs.sparklayer.io/help/platforms/shopify/dawn-theme
Applies to: Shopify

Install SparkLayer's B2B version of Shopify's Dawn theme and set up its B2B login page, forced login, hidden prices, B2B-only products and Quick Buy mode.

> **Quick summary**
>
> - Our B2B version of Shopify's free Dawn theme comes with the SparkLayer frontend code already installed.
> - It adds an optional B2B login page (which can force customers to sign in), hidden prices for signed-out visitors, B2B-only products and menus, and a Quick Buy mode for collection pages.
> - Upload the full theme from [GitHub](https://github.com/sparklayer-io/dawn), with no coding needed, or have your developer copy the changed files into your own Dawn theme. Most optional settings on this page are theme code changes for your developer.

## How it works

Use the B2B Dawn theme if you'd rather start from a theme that's ready for B2B than change your existing one. [Dawn](https://themes.shopify.com/themes/dawn/styles/default) is Shopify's free Online Store 2.0 theme, and the default theme for new Shopify stores. To learn more about it, read Shopify's [guide to the Dawn theme](https://help.shopify.com/en/manual/online-store/themes/os20/themes-by-shopify/dawn).

Our B2B version adapts parts of Dawn to turn on the SparkLayer [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) and add a B2B login page. It includes:

- **A B2B login page** that can force customers to sign in before they see your store, and lets prospective customers apply for an account. You edit its content in the Shopify theme editor.
- **The [product card interface](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md)** on collection pages, showing B2B prices with the option to add to an order.
- **The [product detail interface](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md)**, showing B2B prices with the option to add to an order.
- **The [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) and [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) interfaces.**
- **Quick Buy mode**, a compact collection page layout for building orders quickly.

Dawn is built and maintained by Shopify, so it may change with Shopify's own releases.

## Install the B2B Dawn theme

You need Dawn installed on your Shopify store. Then choose one of these options:

| Option | How | Best for |
| --- | --- | --- |
| **Download the full theme** | Download it from [GitHub](https://github.com/sparklayer-io/dawn/archive/refs/heads/main.zip) and [upload it as a new theme](https://help.shopify.com/en/manual/online-store/themes/adding-themes#upload-a-theme-file-from-your-computer). | A new store: the quickest option |
| **Download our code samples** | Replace the matching files in your Dawn theme. | A Dawn theme you haven't changed yet |
| **Review our code samples** | Apply the changes to your theme files by hand. | A Dawn theme you've already customised |

Downloading the full theme needs no coding. The other 2 options mean editing your theme's code files. So do most of the settings further down this page: forced sign-in, hidden prices, the B2B-only menu and Quick Buy on every collection. If you don't edit theme code yourself, pass this page to your developer, or [contact our support team](https://docs.sparklayer.io/help/support.md) for help.

These are the files that change, with links to the code on GitHub. The full theme is in the [SparkLayer Dawn repository](https://github.com/sparklayer-io/dawn).

| File | What it does | Code |
| --- | --- | --- |
| `layout/theme.liquid` | The main theme file. It loads the SparkLayer Core Script and adds other changes for CSS and forced login. Follow the [frontend integration guide](https://docs.sparklayer.io/developers/frontend.md) to finish setting it up. | [`theme.liquid`](https://github.com/sparklayer-io/dawn/blob/main/layout/theme.liquid) |
| `templates/page.b2b-login.json` | **New file.** The template for the B2B login page. | [`page.b2b-login.json`](https://github.com/sparklayer-io/dawn/blob/main/templates/page.b2b-login.json) |
| `sections/main-b2b-login.liquid` | **New file.** The content of the B2B login page. | [`main-b2b-login.liquid`](https://github.com/sparklayer-io/dawn/blob/main/sections/main-b2b-login.liquid) |
| `sections/main-product.liquid` | The product page, with SparkLayer turned on. | [`main-product.liquid`](https://github.com/sparklayer-io/dawn/blob/main/sections/main-product.liquid) |
| `snippets/card-product.liquid` | The product card, with SparkLayer turned on. | [`card-product.liquid`](https://github.com/sparklayer-io/dawn/blob/main/snippets/card-product.liquid) |
| `templates/customers/register.liquid` | An updated registration page, needed if you use the forced login page. | [`register.liquid`](https://github.com/sparklayer-io/dawn/blob/main/templates/customers/register.liquid) |

To see the theme as a B2B buyer before you publish it, choose it in [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order) and place a test order. When you publish it, step 5 of **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app, **Publish theme**, ticks itself off.

## Create the B2B login page

To use the B2B login page, and to force customers to sign in, create a Shopify page that uses the `b2b-login` template. The page has a sign-in form, a section inviting prospective customers to apply for an account, and an optional set of questions and answers.

1. Add [`sections/main-b2b-login.liquid`](https://github.com/sparklayer-io/dawn/blob/main/sections/main-b2b-login.liquid) and [`templates/page.b2b-login.json`](https://github.com/sparklayer-io/dawn/blob/main/templates/page.b2b-login.json) to your theme, each in the right folder.
2. In your Shopify admin, go to **Online Store > Pages** ([open in the Shopify admin](https://admin.shopify.com/pages)) and click **Add page**.
3. Give the page a title. Under **Edit website SEO**, set the **URL and handle** to `b2b-login`.
4. Under **Online store**, set **Theme template** to `b2b-login`, then save.
5. Visit `www.yourstore.com/pages/b2b-login` to see the new page.

To change how applications work, see [Shopify B2B registration and login](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md).

### Customise the login page

You can change nearly every part of the login page in Shopify's theme editor, including colours, form fields and text.

1. Go to **Online Store > Themes** ([open in the Shopify admin](https://admin.shopify.com/themes)) and click **Customize**.
2. Open the `b2b-login` page from the page selector at the top.
3. Select the **Login Page** section. Its settings include the **Background Image**, **Title**, **Introduction Text**, **Open Account Title**, **Open Account Text** and **Open Account Button Title**. Add **FAQs** blocks to build the questions and answers.

### Force customers to sign in

To make every customer sign in before they can see your store, first [create the B2B login page](#create-the-b2b-login-page). Then edit `layout/theme.liquid` and set this code to `true`:

```javascript
{% raw %}
{% assign showSiteForB2B = true %}
  {% endif %}
{%- if showSiteForB2B == blank -%}
  {% assign showB2BLogin = true %}
{% endif %}
{% endraw %}
```

## Hide prices until customers sign in

You can hide prices on collection and product pages until a B2B customer signs in. Signed-out visitors see a message such as "Please sign in to see pricing" instead.

Set `hidePricesLoggedOut` to `true` in these files:

- `/snippets/card-product.liquid`
- `/sections/main-product.liquid`

In the same files, you can change the text and styling that signed-out visitors see.

## Show products only to B2B customers

The theme can hide chosen products from signed-out visitors. In your Shopify admin, open a product and add the tag `b2b-only` in its **Tags** field. The product then disappears from your collection pages for everyone who isn't signed in.

To change how this works, edit these files:

| File | What it controls | Code |
| --- | --- | --- |
| `sections/featured-collection.liquid` | The featured collection on the homepage | [`featured-collection.liquid`](https://github.com/sparklayer-io/dawn/blob/main/sections/featured-collection.liquid) |
| `sections/main-collection-grid.liquid` | The main collection page | [`main-collection-product-grid.liquid`](https://github.com/sparklayer-io/dawn/blob/main/sections/main-collection-product-grid.liquid) |
| `sections/predictive-search.liquid` | Products shown in the quick search | [`predictive-search.liquid`](https://github.com/sparklayer-io/dawn/blob/main/sections/predictive-search.liquid) |
| `sections/main-product.liquid` | The product page | [`main-product.liquid`](https://github.com/sparklayer-io/dawn/blob/main/sections/main-product.liquid) |

## Show a B2B-only menu

The theme can show B2B customers a different navigation menu from signed-out (retail) visitors. By default, this menu also sets the collections buyers can filter [Catalog and Quick Order](https://docs.sparklayer.io/help/platforms/shopify/catalog-collections.md) by.

1. In your Shopify admin, go to **Online Store > Navigation** ([open in the Shopify admin](https://admin.shopify.com/menus)) and create a menu.
2. Add your menu items. Under **Handle**, enter `b2b-menu`, then click **Save menu**.
3. In these files, set `showB2BNav` to `true`:
   - `snippets/header-mega-menu.liquid`
   - `snippets/header-dropdown-menu.liquid`
   - `snippets/header-drawer.liquid`

```html
{% assign showB2BNav = true %}
```

To test it, sign in as a B2B customer and check the menu.

## Use Quick Buy mode

Quick Buy mode shows a collection as a compact list, so buyers can build orders quickly. Each product has its B2B price and RRP, quantity price breaks, variant drop-downs, quantity controls with any product rules (such as pack sizes) and an **Add** button. To try it, sign in to our [demo store](https://demo.sparklayer.io/) and open the [Quick Buy collection](https://demo.sparklayer.io/collections/sample-quick-buy).

To use it on one collection:

1. In your Shopify admin, go to **Products > Collections** ([open in the Shopify admin](https://admin.shopify.com/collections)) and open the collection.
2. Under **Online Store**, set **Theme template** to `quick-buy`, then save.

To use it on every collection, open `/templates/collection.json` and change the product grid section's type:

```json
"product-grid": {
      "type": "main-collection-product-quick-buy",
```

Quick Buy mode uses its own template files:

- [`/sections/main-collection-product-quick-buy.liquid`](https://github.com/sparklayer-io/dawn/blob/main/sections/main-collection-product-quick-buy.liquid)
- [`/snippets/card-product-quick-buy.liquid`](https://github.com/sparklayer-io/dawn/blob/main/snippets/card-product-quick-buy.liquid)

To change its styling, edit the CSS at the top of `/sections/main-collection-product-quick-buy.liquid`.

Quick Buy mode also applies to signed-out visitors on the collections where you use it. To change that, we recommend working with a Shopify expert.

## Add sample products and prices

If you're starting a B2B store from scratch, load our sample B2B products and prices to see how SparkLayer works before you add your own. You can see them on our [demo store](https://b2b-demo-store-dawn.myshopify.com/).

| Item | How to import it | Download |
| --- | --- | --- |
| **Shopify sample products** | Upload the CSV in your Shopify admin under **Products** | [Sample products CSV](https://cdn.shopify.com/s/files/1/0608/1642/5195/files/Sample_Shopify_Products.csv?v=1635762514) |
| **SparkLayer sample B2B prices** | Upload the CSV in **Pricing > Price lists** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/lists)), or **SparkLayer Wholesale > Pricing > Price lists** in the Shopify app | [Sample B2B prices CSV](https://cdn.shopify.com/s/files/1/0608/1642/5195/files/Sample_SparkLayer_B2B_prices.csv?v=1635762514) |
| **SparkLayer sample metafields** | Upload the CSV with a third-party app such as [Metafields Guru](https://apps.shopify.com/metafields-editor-2) | Not available |

## FAQs

**How do I stop my Shopify prices showing in Google search results?**

Google indexes most Shopify stores, so your Shopify (retail) prices may appear in its search results. This is standard Shopify behaviour, not something SparkLayer controls.

To stop it, you need to customise your Shopify store itself. Shopify Support can advise, and there are [Shopify community articles](https://community.shopify.com/c/forums/searchpage/tab/message?advanced=false\&allow_punctuation=false\&filter=location\&location=category:en\&q=hide%20prices%20from%20google) on the topic. Changes like this can affect your search rankings, so speak to a Shopify expert first.


---

# Shopify Companies

URL: https://docs.sparklayer.io/help/platforms/shopify/companies
Applies to: Shopify

How SparkLayer syncs your Shopify B2B companies, locations and contacts both ways, adds its own pricing and terms, and links orders and vaulted cards.

> **Quick summary**
>
> - Your Shopify B2B companies, their locations and their contacts show in SparkLayer at 
>   **Companies** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/companies)), or **SparkLayer Wholesale > Companies** in the Shopify app
>   , kept in sync both ways. Shopify holds who they are; SparkLayer adds what they buy at.
> - On each company and location, SparkLayer sets the customer group, an optional price list, pay later and the sales agents who look after them. Prices, payment methods and order rules come from SparkLayer, not from Shopify catalog prices or payment terms. A Shopify catalog still controls which products a company sees.
> - SparkLayer links its draft orders to the buyer's Shopify company and location, so orders show under the company and customers can use Shopify's vaulted cards.
> - Companies are optional: customers without one buy at their customer group's settings. Using Shopify Companies may mean extra transaction costs from Shopify, so check with Shopify Support.

## How it works

**Shopify Companies** is part of Shopify's native B2B features, now on every Shopify plan. You find it at **Customers > Companies** ([open in the Shopify admin](https://admin.shopify.com/companies)). A Shopify company has a profile, **locations** (offices, branches or warehouses, each with its own addresses) and **customers** (the contacts who buy for it).

SparkLayer works with those records. It links its draft orders to the buyer's Shopify company, contact and location, so orders show under the company in your Shopify admin.

Each Shopify company is a [company](https://docs.sparklayer.io/help/customers/companies.md) in SparkLayer, and its people are customers at that company. SparkLayer stores its own settings against each company and location:

| Shopify B2B holds | SparkLayer adds |
| --- | --- |
| The company's name and profile | Its **Customer group**, and so its prices, payment methods and order rules |
| Its locations and their addresses | An optional **Price list** for the company or any location |
| Its contacts, who sign in and buy | **Pay later**, and what the company and each location owes |
| | The **Sales agents who look after them** |
| | A [location tree](https://docs.sparklayer.io/help/customers/company-locations.md), and each person's role at a location |

How Shopify companies and SparkLayer work together:

1. **Company in Shopify**: Created in Shopify, or with Create company in SparkLayer
2. **Synced both ways**: The company, its locations and contacts show in SparkLayer, and changes reach the other side
3. **Terms set in SparkLayer**: Customer group, price list, pay later and sales agents
4. **Orders linked**: Draft orders are linked to the company, contact and location in Shopify

SparkLayer still identifies B2B customers by their `b2b` customer tag and puts them in customer groups by their group tag (such as `b2b-trade`). A company's customer group sets the terms for the people at that company. 

## Do you need Shopify Companies?

Companies are optional. Use this table to decide before you set them up.

| If you want to… | Then |
| --- | --- |
| Give a business its own prices, payment terms or sales agents | Use companies. Set the terms on the company in SparkLayer. |
| Let several people buy for one business, or split a business into stores or regions | Use companies and [company locations](https://docs.sparklayer.io/help/customers/company-locations.md). |
| See B2B orders grouped by company in your Shopify admin | Use companies. SparkLayer links their orders automatically. |
| Sell to individual B2B customers on the same terms | You don't need companies. Customer groups handle everything. |

## Set up your companies

Once you've decided to use companies, create them and give each one its terms in SparkLayer.

1. Create your companies in Shopify at **Customers > Companies** ([open in the Shopify admin](https://admin.shopify.com/companies)), or click **Create company** at **Companies** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/companies)), or **SparkLayer Wholesale > Companies** in the Shopify app.
2. In SparkLayer, open each company at **Companies** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/companies)), or **SparkLayer Wholesale > Companies** in the Shopify app and choose its **Customer group**. Give it a **Price list** only if it needs different prices from its group, and turn on **Let them pay later** if it can pay by invoice.
3. Choose its **Main contact** and **Admins** from its people.
4. If the company buys for several stores or regions, click **Manage locations** and set them up. See [Company locations](https://docs.sparklayer.io/help/customers/company-locations.md).
5. Add people to the company: [invite them as buyers](https://docs.sparklayer.io/help/customers/invite-buyers.md) and choose the company, or add them as contacts of the company in Shopify.

See [Companies](https://docs.sparklayer.io/help/customers/companies.md) for every setting on the company page.

## How draft orders are linked to companies

When SparkLayer creates a draft order for a buyer at a company, it links the order to their Shopify **company**, **contact** and **location**. This keeps your Shopify orders and reports accurate.

Linking a SparkLayer order to a Shopify company:

1. **Buyer orders**: A buyer at a company places an order through SparkLayer
2. **Draft order created**: SparkLayer creates a draft order in Shopify
3. **Company linked**: The order is linked to the buyer, their company and the location
4. **Shown in Shopify**: The order appears under both the customer and the company

This means:

- Orders from SparkLayer appear under the company in your Shopify admin. On the orders list, you see the company name under the customer's name.
- Shopify's reports recognise them as B2B orders from that company.
- It resolves Shopify's warning that "Some apps may not attribute B2B orders correctly on your current plan. Check that B2B orders are assigned to a company, not just an individual customer."

## Use vaulted credit cards

Because SparkLayer links draft orders to the customer's company and location, your B2B customers can use [Shopify's vaulted credit cards](https://help.shopify.com/en/manual/b2b/checkout-and-orders/vaulted-cards). They save a card once and reuse it on later orders.

Vaulted cards belong to a **company location**. When a customer saves a card, at checkout or in their customer account, it's available to every customer linked to the same company location. With SparkLayer, they work in 2 ways:

- **Pay Online by Card**: when a customer chooses **Pay Online by Card** in the SparkLayer checkout, the cards saved for their company location appear under **Credit card** in the Shopify checkout. They can choose one, or click **Use a different card**.
- **Draft orders and invoices**: when a customer uses another payment method (for example Pay by Invoice), you can charge a vaulted card on the resulting draft order from your Shopify admin. On the draft order, click **Collect payment** and choose the saved card.

### Before you start

- **Shopify Payments turned on.** Vaulted cards need Shopify Payments as your payment provider.
- **Customers linked to a Shopify company.** The customer must be a contact of a company in your Shopify admin.
- **A saved card.** Someone at the company location must have saved a card during a checkout or in their customer account. Once it's saved, every customer at that location can use it.

There's nothing to set up in SparkLayer. Vaulted cards work in the SparkLayer checkout as long as customers are linked to Shopify companies and Shopify Payments is active. They're available on every Shopify plan that has the Companies feature. Check any transaction fees with Shopify Support.

### Control who can use vaulted cards

To stop some of a customer's team from using vaulted cards, use SparkLayer's [company users](https://docs.sparklayer.io/help/customers/company-users.md) feature. Give those team members the **Limited** role. They can browse and build an order, but they can't check out: their order goes to the main company user for approval instead. Because limited users never reach the Shopify checkout, they can't charge a card saved for the company location.

## Limitations

- **Shopify catalogs still control which products a company sees**: SparkLayer's price lists replace the prices in a Shopify catalog, but not the catalog's product list. If a customer is a contact at a Shopify company whose catalog leaves a product out, Shopify hides it from them: it's missing from your theme's search and its page shows a 404, even when SparkLayer gives them a price. Add the products to the catalog, remove the catalog from the company, or don't use Shopify companies for these customers.
- **Shopify payment terms aren't used**: payment rules come from SparkLayer's customer groups, set on the company or location in SparkLayer. The payment terms on Shopify company records are ignored. 
- **Shopify's locations don't nest**
  : in Shopify, a company's locations sit side by side. Grouping them into regions, with locations inside other locations, is a SparkLayer feature. 

- **Customers linked to several companies**: if a customer is a contact of more than one Shopify company, their draft order may not be linked to a company. 
- **Customers not in a company**: their orders are linked to the customer only.

## FAQs

**Do I need Shopify Companies to use SparkLayer?**

No. Customers who aren't in a company buy at their customer group's settings, and you add them to a group with a tag or an invite. Use companies to see B2B orders grouped by company in Shopify, or to let colleagues share vaulted cards, or when a business needs its own terms, several people buy for it, or it has several locations.

**If I change a company in Shopify, does SparkLayer update?**

Yes. Companies, locations and contacts are kept in sync both ways, so a change in Shopify shows in SparkLayer, and the other way round. Prices, payment terms and sales agents are set in SparkLayer.

**Can I use SparkLayer and Shopify's native B2B checkout at the same time?**

Not for the same customer session: the ordering experience is either SparkLayer or Shopify's native B2B checkout. Your Shopify companies still hold the business, its locations and its contacts, and SparkLayer uses them for ordering.

**Should I tag customers or set up Shopify companies?**

Both work together. Tags (or an [invite](https://docs.sparklayer.io/help/customers/invite-buyers.md), which adds the tag for you) make someone a B2B customer and put them in a customer group. Companies group the people who buy for the same business, and let you give that business its own terms and locations.

**Do I need Shopify Markets to use Shopify Companies?**

Not for SparkLayer pricing. Companies and Markets are separate features, but on plans other than Plus they're closely linked.

You can create company records without Markets. They work as structured customer profiles with locations, contacts and payment terms. But to give those companies their own Shopify pricing catalogs, you need Markets: on the Basic, Grow and Advanced plans, catalogs are assigned through Markets (customer groupings), not directly to companies. On Shopify Plus, you can assign catalogs directly to company locations without Markets.

SparkLayer doesn't use either for pricing. Your price lists and customer groups, and each company's terms, are managed in SparkLayer, whether or not you use Markets.

**What about Shopify's warning that apps may not attribute B2B orders correctly?**

SparkLayer handles it. It links draft orders to the right Shopify company and location, so B2B orders are attributed correctly in your Shopify admin.

## Next steps

- [Add B2B customers on Shopify](https://docs.sparklayer.io/help/platforms/shopify/invite-customers.md): Tag a customer you already have, or add a new one, so they see trade prices
- [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md): Set the pricing and rules your B2B customers get in SparkLayer
- [Shopify limitations](https://docs.sparklayer.io/help/platforms/shopify/limitations.md): What SparkLayer can and can't do on Shopify


---

# Markets and currencies

URL: https://docs.sparklayer.io/help/platforms/shopify/markets-and-currencies
Applies to: Shopify

Show B2B prices in more than one currency on one Shopify store: set up Shopify Markets, create a price list per currency and assign it to a customer group.

> **Quick summary**
>
> - Each B2B customer sees prices, cart totals and checkout amounts in the currency of their customer group's price list, all from one Shopify store.
> - You need a [Shopify Markets](https://help.shopify.com/en/manual/markets) market for each currency, and [Shopify Payments](https://help.shopify.com/en/manual/payments/shopify-payments) active in a supported region.
> - Create one price list per currency 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. SparkLayer doesn't convert prices: you set the exact price in each currency.
> - Shopify's "local currency" setting, duties and market catalogs aren't supported. See [Limitations](#limitations).

## How it works

By default, SparkLayer shows B2B prices in your store's default currency. For example, if your store currency is GBP, every B2B customer sees prices in GBP. With Shopify Markets set up, you can add other currencies, such as USD or EUR. Each customer group then sees prices in its own currency.

When a B2B customer signs in, SparkLayer checks the price list assigned to their customer group. If that price list uses a different currency from your default (for example EUR instead of GBP), the customer sees all B2B prices, cart totals and checkout amounts in that currency. They don't need to switch currency themselves.

Setting it up takes 3 steps: a Shopify market for each currency, a price list in that currency, and a customer group that uses it.

How a customer's currency is chosen:

1. **Customer signs in**: SparkLayer finds their customer group
2. **Group's price list**: The price list has a currency, for example EUR
3. **Prices in that currency**: Product pages, cart and checkout show EUR
4. **Order in Shopify**: The order arrives with EUR as its currency

To see it working, try our [demo store](https://demo.sparklayer.io/pages/b2b-login-register).

## Set up Shopify Markets

Start in Shopify. Each currency you want to use needs a matching, active market.

1. In your Shopify admin, go to **Settings > Markets** ([open in the Shopify admin](https://admin.shopify.com/settings/markets)) (or **Markets** in the main menu if you use Shopify's new Markets experience).
2. Create a market for each region or country where you want to offer a currency. For example, create a "European Union" market with Euro as its currency.
3. Check the market's status is **Active**.
4. Check [Shopify Payments](https://help.shopify.com/en/manual/payments/shopify-payments/supported-countries) is turned on. Multi-currency only works in regions where Shopify Payments is available.

You don't need to set up catalogs or product availability in the market. SparkLayer manages B2B product visibility and pricing itself. The market only needs to exist so Shopify recognises the currency. Next, create a price list in that currency.

## Create a price list in another currency

Each price list has one currency, and you set every price in it yourself.

1. 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.
2. Click **Create price list** (or open an existing price list).
3. Enter a **Name** and a **Handle (or ID)**, and choose the **Currency**, for example EUR, USD or AUD.
4. Add your prices as usual, entering every value in the price list's currency.

You can't change a price list's handle or currency after you've created it. Once the price list is ready, assign it to a customer group.

## Assign the price list to a customer group

The customer group decides which customers see the new currency.

1. 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.
2. Click **Edit** on the customer group, or click **Create customer group** to make a new one.
3. Under **Customized rules**, open **Price lists** and choose the price list in the right currency. Click **Add price list** to add more.
4. Set any other ordering rules, such as a minimum order value. They apply in the price list's currency.
5. Save the group.

A customer group can have several price lists, and the first one with the product's SKU wins: see [Price list order](https://docs.sparklayer.io/help/pricing/managing-pricing.md#price-list-order). All of a group's price lists must use the same currency. If they don't, customers see [PRICING:001](https://docs.sparklayer.io/help/platforms/shopify/error-codes.md).

When customers in the group sign in, they see B2B prices in that currency on product pages, in the cart and at checkout.

## What customers see

Once the group is set up, its customers see their currency everywhere they shop:

- **Product pages**: B2B prices in the customer's currency. A customer on a EUR price list sees euros; a customer on your default GBP price list sees pounds.
- **Cart and checkout**: line items, subtotals and order totals in the customer's currency. The payment methods are the ones set on their [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md).
- **Shipping**: if a customer group has more than one shipping method (for example standard and express), shipping costs are converted from your store's default currency to the customer's currency.

## How orders appear in Shopify

An order placed in another currency arrives in your Shopify admin in that currency. The draft order shows the customer's market, for example "France (EUR €)". How it arrives depends on the payment method:

| Payment method | How the order arrives in Shopify |
| --- | --- |
| **Pay by invoice** | As a draft order |
| **Payment on account** | As a draft order |
| **Card at checkout** | The customer completes the Shopify checkout, so it arrives as a completed order |

To have draft orders turned into completed orders automatically, turn on **Auto-complete draft orders** at **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app.

Because of how Shopify converts currencies and applies discounts, you may see small rounding differences between the price you set and the price on the Shopify order. For example, €7.99 may show as €8.00 in the Shopify admin. This is a Shopify limitation.

## Use Shopify Companies with Shopify Markets

If you use Shopify's Companies feature alongside SparkLayer, multi-currency works in the same way. See [Shopify Companies](https://docs.sparklayer.io/help/platforms/shopify/companies.md) for how SparkLayer works with Companies.

## Limitations

These Shopify Markets features and setups aren't supported, or work differently, with SparkLayer:

- **"Use local currencies"**: in a market with several countries, Shopify can let customers pay in their own region's currency (the market's **Currency** setting, **Use local currencies**). SparkLayer doesn't support this. Choose a single currency for markets with B2B customers, or orders may fail.
- **Price rounding**: small differences can appear between your SparkLayer price and the price on the Shopify order, because of Shopify's currency conversion and rounding.
- **One market per currency**: each currency you offer B2B customers needs its own market in Shopify Markets.
- **Shopify Payments required**: multi-currency only works in regions [where Shopify Payments is available](https://help.shopify.com/en/manual/payments/shopify-payments/supported-countries).
- **Managed Markets and zero-value orders**: with Shopify Managed Markets, you can't create a zero-value B2B order (such as £0.00 or €0.00) in any currency other than your store's default. Customers see an error at checkout if they try. See Shopify's [Managed Markets requirements and considerations](https://help.shopify.com/en/manual/international/managed-markets/requirements-and-considerations#considerations).
- **Duties and import taxes**: if you turn on duties in Shopify Markets, SparkLayer doesn't charge them in the SparkLayer cart. Duties aren't supported.
- **Market catalogs**: if you assign a product collection to a market in Shopify, SparkLayer doesn't detect or enforce it. SparkLayer manages B2B product visibility with its own rules and customer group settings.
- **Currency selectors**: a B2B customer's currency comes from the price list on their customer group, and they can't change it on your store. A currency or country selector in your theme doesn't change the currency of SparkLayer's prices, cart or checkout.

## FAQs

**Do I need Shopify Plus to use multi-currency with SparkLayer?**

No. Multi-currency works on any Shopify plan that supports Shopify Markets and Shopify Payments. Some advanced Markets features, such as the new Markets experience with submarkets and catalogs, are only on Shopify Plus.

**Can I set different B2B prices per currency, or does SparkLayer convert from my default currency?**

SparkLayer doesn't convert prices. You create a price list for each currency and enter the exact prices customers should see, so you control your B2B prices in every currency.

**What happens if there's no Shopify market for the currency of a price list?**

Shopify won't recognise the currency at checkout, which can cause errors when orders are placed (see [SHOPIFY:001](https://docs.sparklayer.io/help/platforms/shopify/error-codes.md)). Make sure an active Shopify market exists for every currency you use in SparkLayer.

**Will the markets I set up for B2B affect my retail customers?**

Shopify Markets apply to your whole store, so retail (B2C) customers in those regions also see the market's currency. SparkLayer's B2B prices stay separate and are only visible to signed-in B2B customers.

**Can one customer group see prices in more than one currency?**

Not from one price list, because each price list has one currency. If customers in the same group need different currencies depending on their region, create a price list per currency and assign the right one to each customer or customer group.

**Why are there small rounding differences on orders in Shopify?**

When SparkLayer sends a B2B order, Shopify applies its own currency conversion and discount calculations, which can cause small rounding differences (for example €7.99 becoming €8.00). This is a Shopify limitation.

**Does SparkLayer use Shopify's automatic exchange rates?**

No. SparkLayer uses the fixed prices you set in each price list, so Shopify's automatic exchange rates don't apply to B2B prices. You control the exact price customers see.


---

# Metafields and data mapping

URL: https://docs.sparklayer.io/help/platforms/shopify/metafields
Applies to: Shopify

Let SparkLayer add its Shopify metafields, fill them in for many products at once in the bulk editor, map order data and import order history.

> **Quick summary**
>
> - SparkLayer reads Shopify metafields for B2B settings such as pack sizes, RRP and credit limits. The [Metafields](https://docs.sparklayer.io/developers/data/metafields.md) reference lists every one.
> - Metafields are optional. You don't need any to install SparkLayer or start taking B2B orders. Add them only when you want a feature that uses one.
> - SparkLayer creates the fields for you at **Integrations > Platform > Metafields** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Metafields** in the Shopify app. Fill them in on one product or customer, or on hundreds at once in Shopify's bulk editor.
> - Where a value has a set format (JSON), the feature's page has a **Build the value** form that writes it for you.

## How it works

[Metafields](https://help.shopify.com/en/manual/custom-data/metafields) are extra fields you can add to products, customers and orders in Shopify, to store information Shopify doesn't capture by default. Each SparkLayer metafield turns on or configures a specific B2B feature:

| Type | What SparkLayer uses them for |
| --- | --- |
| **Product metafields** | Settings for the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md), such as [pack sizes](https://docs.sparklayer.io/help/storefront/quantity-rules.md) and [RRP prices](https://docs.sparklayer.io/help/pricing/pricing-display.md) |
| **Customer metafields** | Customer settings, such as [credit limits](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) |
| **Order metafields** | Order details, such as [invoicing information](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) |

Setting one up takes two steps: SparkLayer [adds the field](#add-metafields-automatically) once, then you [fill it in](#fill-in-metafields). Keep two things in mind:

- **Product metafields go on variants.** Fill them in on each product variant, never the product, even if the product has only one variant.
- **Some values are JSON.** A few settings, such as credit limits, are written in a set format (JSON), for example `{"net_terms":"30_days"}`. Their pages have a **Build the value** form that writes it for you to copy.

## Add metafields automatically

SparkLayer can create its metafields in Shopify for you. This is the easiest way to add them, and needs no technical knowledge.

1. 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.
2. In the **Metafields** card (**SparkLayer metafields**), click **Configure**.
3. The **Metafield Configuration** window lists the metafields you can add for **Product** and **Customer** data, such as **Pack Size**, **Reserved DTC Stock Quantity**, **Restock Date** and **Stock Location Settings**. Click **Enable** beside each one you want. The metafield shows a green tick.

SparkLayer only reads a metafield once it's enabled here. If you've created a definition yourself in Shopify, enable it here too.

Each metafield you enable is added to **Settings > Custom data** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data)) in Shopify and pinned, so it appears at the top of the metafields on each product or customer. Its name starts with `B2B -`, for example `B2B - Pack Size`.

To change or remove these metafields, go to **Settings > Custom data** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data)) in Shopify.

## Fill in metafields

Once a field exists, fill it in whichever way suits how many products or customers you're changing.

### One product or customer

Open the product variant, customer or order in Shopify and enter the value in its **Metafields** card. Click **Show all** if you can't see the field.

For example, you can set [payment terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) on a customer, such as `{"net_terms":"30_days"}`, or a [customer-specific discount](https://docs.sparklayer.io/help/pricing/customer-pricing.md) (**Customer % Discount**).

### Many at once

Shopify's bulk editor shows a metafield as a column, so you can fill in hundreds of products or customers in one table, without opening each one:

1. In your Shopify admin, go to **Products** ([open in the Shopify admin](https://admin.shopify.com/products)) or **Customers** ([open in the Shopify admin](https://admin.shopify.com/customers)) and tick the ones to change. To change them all, tick the box at the top of the list.
2. Click **Edit products** or **Edit customers**.
3. Click **Columns** and, under **Metafields**, tick the SparkLayer fields you want, such as **B2B - Pack Size**.
4. Type each value. For products, each variant has its own row.
5. Click **Save**. If a value is in the wrong format, Shopify highlights it: fix it and click **Save** again.

See Shopify's guide to [editing metafields in bulk](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

### From a spreadsheet

For thousands of rows, or values you already keep in a spreadsheet, use an import app. We recommend [Matrixify](https://apps.shopify.com/excel-export-import), which reads metafield columns from a spreadsheet and imports them in bulk.

## Add metafields by hand

You only need this for a metafield SparkLayer doesn't create for you. Add a metafield definition in Shopify, then [fill in its value](#fill-in-metafields). Shopify's [metafields guide](https://help.shopify.com/en/manual/custom-data/metafields) covers this in full.

1. In your Shopify admin, go to **Settings > Custom data** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data)).
2. Choose where the metafield goes: **Variants** for product metafields, **Customers** or **Orders** for the others.
3. Click **Add definition** and fill in the fields below.
4. Click **Save**.

| Field | What to enter |
| --- | --- |
| **Name** | A name your team will recognise, for example `B2B - MSRP Pricing (RRP)` |
| **Namespace and key** | `sparklayer.` followed by the key, for example `sparklayer.pack_size` or `sparklayer.rrp`. The namespace must be `sparklayer`. |
| **Type** | The data type, for example a text field, JSON or a list of values. The [Metafields](https://docs.sparklayer.io/developers/data/metafields.md) reference gives the type for each setting. |

> **Common mistake: wrong namespace**
>
> In the Shopify admin, the namespace and key are one field, **Namespace and key**. Shopify fills it in from the name you type, starting with `custom.`, so a definition named "B2B - Settings" becomes something like `custom.b2b_settings`. SparkLayer never reads that field. Replace the whole value with the exact SparkLayer namespace and key, for example `sparklayer.settings` (type **JSON**, on **Variants**) or `sparklayer.pack_size` (type **Integer**).

### Set up the sales agent groups metafield

If you use the sales agent groups metafield (`sparklayer.sales_agent_groups`), its definition must be set to **Limit to preset choices**. Each sales agent group is then a choice in a dropdown on the customer. If the metafield takes free text instead, customers can show sync errors.

1. In your Shopify admin, go to **Settings > Custom data** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data)) and click **Customers**.
2. Open the sales agent groups definition. If there isn't one, click **Add definition** and use the namespace and key `sparklayer.sales_agent_groups`, with a list of single line text as the **Type**.
3. Turn on **Limit to preset choices**.
4. Add each of your sales agent groups as a choice, then click **Save**.

Customers who had sync errors from this metafield sync on the next partial sync. See [Product and customer sync](https://docs.sparklayer.io/help/integrations/data-sync.md#fix-customer-sync-errors).

## Import order history into SparkLayer

You can import historic B2B orders into SparkLayer, so customers see their previous orders when they sign in to their account on your store. Do this after SparkLayer is installed, so the orders sync correctly.

1. Add an order metafield definition with these settings:

   | Field                | Value          |
   | -------------------- | -------------- |
   | **Custom data type** | Order          |
   | **Metafield type**   | `boolean`      |
   | **Namespace**        | `sparklayer`   |
   | **Key**              | `order_import` |

2. On each order you want to import, set the metafield's value to `true`.

3. Make sure each of those orders has the tag `b2b` in Shopify.

Synced orders appear in the Orders section of the SparkLayer Dashboard and are included in reporting.

For a large number of orders, use a bulk import tool such as [Matrixify](https://apps.shopify.com/excel-export-import?st_source=autocomplete). Start from our [sample CSV template](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/example-historic-order-import.csv?v=1738672207), or put the Shopify order ID in the `ID` column in this format:

| ID | Metafield: sparklayer.order\_import \[boolean] | Command |
| --- | --- | --- |
| `[order-id-here]` | `TRUE` | `UPDATE` |

## Set a custom order number

You can show customers your own order number instead of the one Shopify generates, for example to match order numbers from your back-office system (such as an ERP). SparkLayer calls this the **Visible ID**. Customers see it as the order **Reference** in the [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md).

Add an order metafield with these settings, then enter your order number on each order:

| Field | Value |
| --- | --- |
| **Custom data type** | Order |
| **Metafield type** | `single line text` |
| **Namespace** | `sparklayer` |
| **Key** | `visible_id` |

Orders without a Visible ID show the standard Shopify order number.

## Order data reference (for developers)

This section is technical reference for your developer or integration partner. You don't need it to use SparkLayer.

When SparkLayer sends an order to Shopify, it adds these details to the order:

| Attribute | Notes |
| --- | --- |
| `note` | Order note attribute `sparkCartId`. Mainly for our internal debugging. |
| `note` | Order note attribute `sparkPaymentType`: the payment option used. One of `upfrontPayment`, `paymentOnAccount`, `paymentByInvoice` or `quote`. |
| `tag` | The tag `b2b`, added to every order placed through SparkLayer. |

Each line item also has a `Charged Price` attribute with the final line price. On the order in Shopify, these appear under **Additional details**, and each line item shows its **Charged Price**. 

### Order mapping

How Shopify order fields map to SparkLayer order fields:

| Shopify | SparkLayer |
| --- | --- |
| `processsed_at` | `created_at` |
| `id` | `external_id` |
| `name` | `visible_id` |
| `currency` | `currency_code` |
| `note` | `customer_reference` |
| `customer.id` | `customer_id` |
| `billing_address` | `billing_address` |
| `shipping_lines[0].title` | `packages[0].shipping_name` |
| | `packages[0].shipping_sku` === 'shopify' |
| `shipping_address` | `packages[0].shipping_address` |
| `shopifyOrder.shipping_lines[X].price (SUM)` | `packages[0].total_shipping_.gross` |
| `shopifyOrder.shipping_lines[X].tax_lines.price (SUM)` | `packages[0].total_shipping_.net` |
| `line_items[T].name` | `packages[0].items[T].name` |
| `line_items[T].quantity` | `packages[0].items[T].quantity` |
| `line_items[T].id` | `packages[0].items[T].variant_id` |
| `(T)` | `packages[0].items[T].line_total.gross` |
| `(T)` | `packages[0].items[T].line_total.net` |

## Advanced settings

For customer-level product metafield settings and other advanced options, see [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md).


---

# Collections in Catalog and Quick Order

URL: https://docs.sparklayer.io/help/platforms/shopify/catalog-collections
Applies to: Shopify

Choose which Shopify collections buyers filter Catalog and Quick Order by: SparkLayer follows a navigation menu, in its order and nesting.

> **Catalog and Quick Order is in early access.** Request it for your store. [Request early access](https://feedback.sparklayer.io/get-started?choice=now).

> **Quick summary**
>
> - Buyers and sales reps can filter [Catalog and Quick Order](https://docs.sparklayer.io/help/sales-ordering/catalog.md) by collection. On Shopify, the collections come from one of your navigation menus, in the menu's order and nesting.
> - By default, SparkLayer follows your `b2b-menu`, then your `main-menu`. You can choose another menu, or every collection, at **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app.
> - A buyer only sees a collection when it has products they can see.

## How it works

A Shopify store usually has far more collections than it shows customers: collections for discounts, product feeds, homepage sections or old sales. Your navigation menu is where you choose which collections customers browse, and in what order, so SparkLayer follows it too.

With the default **Automatic** setting, SparkLayer picks the menu like this:

1. Your `b2b-menu`, if it links to at least 1 collection. It's the menu our [B2B-only navigation guide](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-only-content.md#show-a-b2b-only-navigation-menu) and the [Shopify B2B Dawn theme](https://docs.sparklayer.io/help/platforms/shopify/dawn-theme.md) set up for signed-in B2B customers.
2. Otherwise your `main-menu`, if it links to at least 1 collection.
3. Otherwise every collection published to SparkLayer, A to Z, with no nesting.

A collection in the menu doesn't need to be published to SparkLayer itself. Its products do.

## What the filter shows from a menu

| In your menu | In the filter |
| --- | --- |
| A collection, or a link to `/collections/your-collection` | The collection, under its own title, in the menu's order. A link with a tag or a language prefix counts as the collection |
| **All products** or **All collections** | Nothing of its own, since the filter already has **All collections**. Anything under it moves up a level |
| Any other item (a page, a blog, a `#` link) with collections under it | A heading that groups those collections, under the menu item's title. Choosing it shows the products of every collection under it |
| A heading with a child collection of the same title (Women › Shop all, linking to the Women collection) | The collection, with the heading's other children under it |
| A collection that appears twice | Shown once, where it first appears. Anything under the second one moves up a level |
| A link to a collection your store doesn't have | Left out. Anything under it moves up a level |
| A page, blog or link with no collection under it | Left out |

If your whole menu sits under one heading, such as **Shop**, the filter starts one level down.

## Choose the menu

1. Go to **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app.
2. In the **Categories** card, under **Where categories come from**, choose:
   - **Automatic**: your `b2b-menu`, then your `main-menu`, then every collection.
   - **A menu you choose**: pick any of your store's menus.
   - **Every published collection**: every collection published to SparkLayer, A to Z.
3. Click **Save**. SparkLayer syncs your collections straight away.

The card shows what your current setting and menu give, and any menu items left out, with the reason. If buyers don't have those categories yet, for example after a menu edit, the card says **Not in the catalogue yet**: click **Save** to sync them.

> **Want a different structure for B2B buyers?**
>
> Create a menu with only the collections your B2B buyers order from, at **Online Store > Navigation** ([open in the Shopify admin](https://admin.shopify.com/menus)), and choose it on the **Categories** card. With the **Automatic** setting, giving it the handle `b2b-menu` works too. You can also [show the same menu in your store's header](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-only-content.md#show-a-b2b-only-navigation-menu) to signed-in B2B customers.

## When changes show

- **Renaming or deleting a collection** updates the filter within a few minutes.
- **A new collection, or a collection's products changing** shows when those products next sync. Adding products to a manual collection, or changing a smart collection's conditions, doesn't change the products themselves, so it shows at the next full product sync.
- **Menu changes:** Shopify doesn't tell apps when a menu changes. After reordering a menu, or adding or removing a collection in it, click **Save** on the **Categories** card. Otherwise it shows after the next collection change or full product sync.

A full product sync is run by our team: [contact support](https://docs.sparklayer.io/help/support.md) and we'll run one for you.

## FAQs

**Why does the Categories card ask me to approve permissions?**

Reading your navigation menus needs a permission SparkLayer didn't ask for before. Open the SparkLayer app in your Shopify admin and approve the updated permissions. Until you do, the filter shows every collection published to SparkLayer.

**A collection is in my menu but buyers can't see it**

A buyer only sees a collection when it has products they can see, so check its products are published to SparkLayer and visible to that buyer's customer group. If the collection is in the menu twice, it shows only where it first appears. If you added it recently, it shows once its products next sync.

**Can I hide a collection without changing my store's menu?**

Yes. Create a separate menu with only the collections you want, and choose it on the **Categories** card. Your store's own navigation stays as it is.

**Does the menu control which products buyers can order?**

No. The menu only decides which collections appear as filters. Which products a buyer can see is set by [product visibility for customer groups](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-advanced-catalogs.md) and your price lists.


---

# Shopify FAQs

URL: https://docs.sparklayer.io/help/platforms/shopify/faqs
Applies to: Shopify

Answers to common Shopify questions: plans, Shopify B2B, themes, customers who see retail prices, products, payments, draft orders and checkout errors.

## Setup and plans

**Where do I find SparkLayer in my Shopify admin?**

Under **Sales channels**, click **SparkLayer Wholesale**. It opens on **Home**, and the menu items below it open each area, such as **Setup**, **Pricing** and **Customers**. See [How it works](https://docs.sparklayer.io/help/platforms/shopify.md#how-it-works). The same screens are in the SparkLayer Dashboard at [app.sparklayer.io](https://app.sparklayer.io/), which also has **Forms** and **Data tables**.

**What's the quickest way to set SparkLayer up?**

Work through the steps at **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app: a price list, a customer group, your first buyer and your theme. Most stores finish in under 15 minutes. See [Install SparkLayer on Shopify](https://docs.sparklayer.io/help/platforms/shopify/install.md).

**Which Shopify plan do I need to use SparkLayer?**

Any plan. SparkLayer works on every Shopify plan, from Shopify Basic to Shopify Plus, with customer accounts turned on so your B2B customers can sign in. Your Shopify plan is separate from your SparkLayer plan: see the next question.

**Which SparkLayer plan do I need, and can I try it on a development store?**

Any of them. The free **Basic** plan, only on Shopify, includes 3 price lists and 5 B2B orders a month, with no sales agents. The paid plans (Starter, Growth, Pro and Enterprise) add unlimited price lists, more orders, sales agents and more features, each with a 14-day free trial. You're billed through Shopify. See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).

On a development store, such as a test account, we can turn on a developer mode, so you can use SparkLayer before you choose a plan. [Contact us](https://docs.sparklayer.io/help/support.md) to set it up.

**How does SparkLayer compare to Shopify B2B?**

Shopify's native B2B features, such as companies, catalogs and payment terms, are on every Shopify plan, but what they can do depends on your Shopify plan: check Shopify's [B2B guide](https://help.shopify.com/en/manual/b2b). For a few wholesale accounts on simple terms, that may be enough. SparkLayer adds, on any Shopify plan:

- **Pricing**: price lists assigned to customer groups (3 on Basic, unlimited on paid plans), prices for one customer and quantity pricing.
- **Sales team ordering**: sales agents order on your store at each customer's prices, from the Starter plan.
- **B2B ordering**: CSV upload to the cart, shopping lists and quick reordering on every plan, plus AI file upload, discounts, SparkLayer Invoices and quotes on higher plans. See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
- **Your own theme**: B2B ordering on your existing Shopify theme.

SparkLayer works alongside Shopify Companies, but SparkLayer and Shopify's native B2B checkout can't run side by side for the same customer: the ordering experience is one or the other. Using Shopify Companies may mean extra transaction costs from Shopify, so check with Shopify Support.

For a full comparison, read [SparkLayer vs Shopify B2B: what you need to know](https://sparklayer.io/blog/2026/04/03/shopify-b2b-all-plans/).

**Can I run retail (DTC) and B2B on the same Shopify store?**

Yes. Install SparkLayer on your existing retail store and run both from one store, a hybrid setup. Signed-in B2B customers see SparkLayer's [frontend interfaces](https://docs.sparklayer.io/help/storefront.md) with their prices and B2B ordering; retail customers see your store as it is. To see it working, [try our demo](https://docs.sparklayer.io/help/get-started/demo.md).

Retail and B2B then share one stock pool, apps and reporting, so sometimes a separate B2B store works better: see [One store or a separate B2B store](https://docs.sparklayer.io/help/platforms/shopify/customisations/store-setup.md).

**Which version of Shopify customer accounts does SparkLayer work with?**

Both. Shopify has two versions of customer accounts:

- **Legacy** (formerly "classic"): customers sign in with an email and password. Most Shopify stores use this. It works with third-party apps, and you can customise how it looks.
- **Customer accounts** (new): customers sign in without a password, using a one-time code, and the account area is Shopify's own, much like the checkout.

New customer accounts need a small extra step: turning on the **B2B Account Redirect**. See [Choose your customer accounts version](https://docs.sparklayer.io/help/platforms/shopify/install.md#choose-your-customer-accounts-version).

**Does SparkLayer support Shopify Companies?**

Yes, and they're optional. SparkLayer links its draft orders to the buyer's Shopify company, contact and location, so orders show under the company in your Shopify admin, and customers at a company location can use its vaulted cards. Prices, payment methods and order rules still come from SparkLayer, not from Shopify catalogs or payment terms. See [Shopify Companies](https://docs.sparklayer.io/help/platforms/shopify/companies.md).

**How do I cancel, downgrade or uninstall SparkLayer?**

- **To stop paying but keep your setup**, move to the free **Basic** plan at **Plan card** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Plan** in the Shopify app, without uninstalling.
- **To cancel**, uninstall **SparkLayer Wholesale** at **Settings > Apps and sales channels** ([open in the Shopify admin](https://admin.shopify.com/settings/apps)). Billing stops straight away.

Treat uninstalling as deleting your SparkLayer data. Export what you need first, such as your price lists, and [contact us](https://docs.sparklayer.io/help/support.md) before you uninstall if you might reinstall or move to another store. Billing and refunds go through Shopify. See [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md) and [Cancel, uninstall or transfer SparkLayer](https://docs.sparklayer.io/help/platforms/shopify/uninstall.md).

**What is the B2B Ordering pixel in my Shopify customer events?**

It tells SparkLayer when a customer has paid by card through the Shopify checkout. SparkLayer needs to know the order is complete, so it can clear their cart and let them place more orders. The **B2B Ordering** pixel is added automatically when you install SparkLayer, so you don't usually need to do anything. 

To check it's there:

1. In your Shopify admin, go to **Settings > Customer events** ([open in the Shopify admin](https://admin.shopify.com/settings/customer_events)).
2. On the **App pixels** tab, look for **B2B Ordering**. Its status should be **Connected**.

If it's missing, reconnect your store: 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 and save the page. This turns the pixel on.

**Can I delete old SparkLayer scripts from Additional Scripts?**

Yes, once the B2B Ordering pixel is connected. Older installs added SparkLayer code (a thank-you page script or order status script) through **Additional Scripts** in Shopify's checkout settings. The pixel in Shopify's customer events now does that job, so the old scripts aren't needed.

1. Check the **B2B Ordering** pixel shows **Connected** in **Settings > Customer events** ([open in the Shopify admin](https://admin.shopify.com/settings/customer_events)), as described in the question above.
2. Go to **Settings > Checkout** ([open in the Shopify admin](https://admin.shopify.com/settings/checkout)) and find **Additional Scripts**.
3. Delete any old SparkLayer checkout or thank-you page scripts, then save.

## Theme and storefront

**Can you install SparkLayer on my Shopify store for me?**

Yes, free of charge, on every plan. Click **Something not right? Install SparkLayer for me** on **Home > Setup > Theme setup** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Setup > Theme setup** in the Shopify app, or **Request installation** at **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app. We'll be in touch, usually within a working day. On a paid plan, we'll also offer an onboarding session to walk you through how everything works. Theme customisation, such as restyling the widgets or page builder pages, isn't included. See [Ask our team to install it](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md#get-our-team-to-install-it).

**Does SparkLayer work with any Shopify theme or page builder?**

It works with every Shopify theme, including Online Store 2.0 and heavily customised themes. On [supported themes](https://docs.sparklayer.io/help/platforms/shopify/install.md#automatic-install-on-supported-themes), such as Dawn and Horizon, it adds the product page and product card interfaces automatically. You can also start with our [B2B Dawn theme](https://docs.sparklayer.io/help/platforms/shopify/dawn-theme.md).

Two set-ups need checking:

- **Page builder apps**, such as PageFly or Shogun. Their pages use their own layout, so they may not include SparkLayer's widgets, and B2B customers can see retail prices and **Add to cart** buttons there.
- **A theme copied from another store.** It can carry that store's SparkLayer code. Remove it and set SparkLayer up again on the copy.

See [Page builders and copied themes](https://docs.sparklayer.io/help/storefront/what-you-can-change.md#page-builders-and-copied-themes), and tell us about either when you request installation.

**How do I check SparkLayer is on my theme, for example after a theme update?**

Go to **Home > Setup > Theme setup** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Setup > Theme setup** in the Shopify app. It shows your theme's status and each SparkLayer app block: the required **SparkLayer** and **B2B Account Redirect** blocks, and the optional **Product block** and **Product card block**. Turn a missing block on with **Edit** or **Add**, which opens Shopify's theme editor at that block, or click **Something not right? Install SparkLayer for me**. See [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md).

After you update or change your theme, check again: choose the new theme under **Select theme** on **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app first. App blocks aren't always carried across, and a theme update can remove SparkLayer code added to your theme files. SparkLayer only shows to signed-in B2B customers, so to see it on your store, use [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order).

If SparkLayer's styles stop working after you publish a theme, it may be loaded twice: see [Styles stop working after you publish a theme](https://docs.sparklayer.io/help/troubleshooting.md#styles-stop-working-after-publishing).

**Will SparkLayer change my store for retail customers, or slow it down?**

No. SparkLayer's widgets, including B2B pricing, the cart and the account area, only load when a B2B customer (tagged `b2b`) signs in. Retail shoppers and signed-out visitors see your store as it is, and no SparkLayer code loads for them. For B2B customers, the widgets load asynchronously, so the effect on page load times is negligible.

**Does SparkLayer work with my theme's variant image switcher?**

Not out of the box. SparkLayer's widgets replace your theme's product buying area for B2B customers, and load your variants, SKUs and product data themselves. Many themes change the main product image when a customer picks a variant, using custom JavaScript written for that theme. SparkLayer's widgets don't trigger it, so the image doesn't change for signed-in B2B customers.

A Shopify developer can connect the two for your theme using the [JavaScript SDK](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md#update-the-product-image-when-a-variant-is-selected).

**What if I already use a wholesale app on my store?**

SparkLayer can run alongside it, so you can test SparkLayer first. When you're happy, uninstall your previous B2B app. If that app changed your theme code, you can ask its developer to remove the changes, but you don't have to. See [Move your existing wholesale customers onto SparkLayer](https://docs.sparklayer.io/help/guides/move-existing-customers.md).

**How do I set up a B2B registration form?**

We recommend one of these 2 options:

- **SparkLayer Forms (recommended)**: our built-in, no-code form builder. Start with the ready-made **Customer Registration Form** template, which includes approval workflows, automatic customer tagging and email notifications, with no third-party app needed. Forms are in the SparkLayer Dashboard at **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)), not in the Shopify app. See [SparkLayer Forms](https://docs.sparklayer.io/help/forms.md).
- **B2B login and registration page**: a free, ready-made template that adds a B2B login and registration page to your store (for example `yourstore.com/pages/b2b-login`). It has a login form for existing customers and an application form for new ones, and you can customise it in the Shopify theme editor. Our team can install it for you free of charge. See [Shopify B2B registration and login](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md).

You can also invite buyers yourself with **Invite a buyer** (see [Invite a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md)), or add customers by hand in your Shopify admin under **Customers**. The **Copy registration link** button in the invite window copies a link to your store's trade registration page.

**How do I stop my Shopify prices showing in Google search results?**

Google indexes most Shopify stores, so your Shopify (retail) prices may appear in its search results. This is standard Shopify behaviour, not something SparkLayer controls.

To stop it, you need to customise your Shopify store itself. Shopify Support can advise, and there are [Shopify community articles](https://community.shopify.com/c/forums/searchpage/tab/message?advanced=false\&allow_punctuation=false\&filter=location\&location=category:en\&q=hide%20prices%20from%20google) on the topic. Changes like this can affect your search rankings, so speak to a Shopify expert first.

## Customers

**How do I make a Shopify customer a B2B customer?**

Add the tag `b2b` to their customer record in Shopify. To put them in a [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md) other than Base, add that group's tag as well, for example `b2b-vip`. Use no more than 2 B2B tags, and make sure they have at least one complete address. You can tag many customers at once from Shopify's customer list. Or invite them with **Invite a buyer**, on step 3 of **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app or at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app, and SparkLayer adds them to Shopify with the right tags.

To let a new customer know they can sign in: with Legacy customer accounts, click **Send account invite** on their Shopify record; with new customer accounts, send them a link to your store's sign-in page. See [Add B2B customers on Shopify](https://docs.sparklayer.io/help/platforms/shopify/invite-customers.md). To change the invitation email, see [Shopify email notifications](https://docs.sparklayer.io/help/platforms/shopify/customisations/email-notifications.md#b2b-customer-account-invite-email).

**Why does a B2B customer see retail prices, or can't sign in?**

Check these in order:

1. **Their tags**: `b2b`, plus a group tag with the `b2b-` prefix that matches a group at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app, and no more than 2 B2B tags.
2. **Their addresses**: every saved address needs a country, first line, city and postcode or ZIP code.
3. **The email they sign in with**: with new customer accounts, a different or mistyped email creates a separate retail account without the `b2b` tag.
4. **An old session**: try a private (incognito) window.
5. **Your theme**: SparkLayer must be on your published theme, not only a copy.

See [A B2B customer can't sign in or sees retail prices](https://docs.sparklayer.io/help/troubleshooting.md#b2b-customer-cant-sign-in-or-sees-retail-prices) for every check.

**Can my sales reps order for customers, including in Shopify POS?**

Yes, on your online store. Make them a sales agent at **Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app, from the Starter plan. They sign in on your store, choose a customer and order at that customer's B2B prices. See [Sales rep setup](https://docs.sparklayer.io/help/sales-reps.md) and [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md).

Our guides don't cover Shopify POS, so [contact us](https://docs.sparklayer.io/help/support.md) before you plan around it.

## Products

**Why does a product show "Unavailable" or no B2B price?**

Usually the product hasn't reached SparkLayer, or the customer's price list has no price for it. Check the product:

- Has a **unique SKU** on every variant.
- Is **Active** in Shopify, not Draft.
- Is published to the **SparkLayer Wholesale** sales channel.
- Has a **price for that SKU** in a price list on the customer's group. If you uploaded a CSV, the SKUs must match Shopify exactly.

See [Customers can't see B2B prices, or products say "Unavailable"](https://docs.sparklayer.io/help/troubleshooting.md#customers-cant-see-b2b-prices-or-products-say-unavailable) and [Why a product shows Unavailable](https://docs.sparklayer.io/help/pricing/managing-pricing.md#unavailable).

**Do my products need SKUs?**

Yes. SparkLayer uses SKUs to show the right B2B price when a customer signs in, so every product variant needs a SKU in Shopify, and each SKU must be unique.

If your products don't have SKUs yet, you can add them by editing each product, or in bulk with Shopify's import or bulk edit tools.

**How do I hide products or set up B2B-only products?**

Use [B2B Catalogs](https://apps.shopify.com/sparklayer-b2b-catalogs), a free SparkLayer app that controls which products each type of customer can see on your Shopify store. You can hide products from retail customers, make products B2B-only, or show different ranges to different customer groups, all with tags and no code.

Install B2B Catalogs from the Shopify App Store, then follow the [B2B Catalogs documentation](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md) to set it up. To hide variants from particular customer groups, see [Product settings](https://docs.sparklayer.io/help/storefront/product-settings.md#what-hides-what).

To hide products from B2B customers or some customer groups in SparkLayer, including [Catalog and Quick Order](https://docs.sparklayer.io/help/sales-ordering/catalog.md), see [Hide products from customers](https://docs.sparklayer.io/help/guides/hide-products.md). A form writes the setting, and your AI assistant can apply it to every product.

**Can I hide one variant of a product from retail customers?**

No. Shopify can't hide a single variant from retail shoppers, and SparkLayer's variant settings only apply to signed-in B2B customers. To keep one variant for B2B customers only, such as a 12-pack case, make it a separate product and tag it `b2b-only` with B2B Catalogs. See [What hides what](https://docs.sparklayer.io/help/storefront/product-settings.md#what-hides-what).

**Can I base my B2B prices on my Shopify prices?**

Yes. An automatic price list calculates B2B prices from your Shopify prices, for example 20% off your Shopify price or your compare-at price. If your Shopify prices include tax, set a percentage that takes the tax out too, because SparkLayer shows prices net. See [Managing pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md) and [Tax-inclusive prices](https://docs.sparklayer.io/help/pricing/managing-pricing.md#tax-inclusive-prices).

**Do bundles from other apps get B2B prices?**

Only if the bundle is a regular Shopify product with its own unique SKU. SparkLayer matches B2B prices to products by SKU, so it treats a bundle (or kit) like any other product.

Shopify's own Bundles app isn't supported. Shopify doesn't let you publish its bundle products to the SparkLayer Wholesale sales channel, so SparkLayer never receives them, and B2B customers get no price or buy buttons for them.

Bundle apps that create a regular product with its own SKU do work. Our support team has seen merchants use Fast Bundle and Simple Bundles & Kits (which has a free tier). Whichever app you use, check that the bundle product:

- Has its **own unique SKU**.
- Is **Active**, not Draft. Draft products don't sync to SparkLayer.
- Is published to the **SparkLayer Wholesale** sales channel.
- Has a **price for that SKU** in the customer's price list.

Also check the app builds bundles from your existing Shopify products and adjusts their stock when a bundle sells. To keep a B2B bundle away from retail shoppers, tag it `b2b-only` with [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md).

**How do I set up pre-order and back-order products?**

In Shopify, open the product or variant, tick **Track quantity** and **Continue selling when out of stock**, and set the available quantity to 0 or less. B2B customers then see a pre-order message, and you can show a restock date. "Continue selling when out of stock" applies to retail customers too, so to keep pre-orders for B2B customers only, make them separate B2B-only products. See [Allow pre-orders and back-orders](https://docs.sparklayer.io/help/storefront/stock-display.md#allow-pre-orders-and-back-orders).

**How do I keep B2B customers from using my retail stock (and the other way round)?**

If you run retail and B2B on one store, both use the same stock pool. SparkLayer can reserve stock for your retail customers, so B2B customers can't order too much of a product. See [Reserve stock for retail customers](https://docs.sparklayer.io/help/storefront/stock-display.md#reserving-stock).

You can't stop retail customers ordering from your stock, because Shopify has no way to do this. If you need to, consider:

- Creating B2B-only products on your store. See [B2B-only content](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-only-content.md).
- Creating a separate store just for B2B customers, so your stock is completely separate. See [One store or a separate B2B store](https://docs.sparklayer.io/help/platforms/shopify/customisations/store-setup.md).

**What doesn't SparkLayer support on Shopify?**

The limits most stores meet are:

- **Shopify discounts** can't be used alongside SparkLayer. Use SparkLayer's own discounts instead.
- **Carts hold up to 350 line items** by default. Our [support team](https://docs.sparklayer.io/help/support.md) can raise this to 500.
- **Tax-inclusive prices, duties and orders that mix taxable and tax-exempt products** need a workaround, often a separate B2B store.
- **Product options added by other apps**, such as a text-entry field, don't show in SparkLayer's widgets. A developer can add them with the JavaScript SDK.
- **Subscriptions** from subscription apps aren't supported in SparkLayer's B2B cart. 

See [Shopify limitations](https://docs.sparklayer.io/help/platforms/shopify/limitations.md) for each one and its workaround.

## Payments

**How do B2B payments work with SparkLayer and Shopify?**

You choose the B2B payment methods for each [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md#choose-payment-methods). Card payments go through the Shopify checkout and arrive as paid orders. Pay on Account and Pay by Invoice orders arrive as draft orders for you to complete. The diagram shows how they work with Shopify. See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md) and [Shopify payment methods](https://docs.sparklayer.io/help/platforms/shopify/customisations/payment-methods.md).

How B2B payment methods work with SparkLayer and Shopify, starting from the B2B checkout (SparkLayer):

- **Pay online by card (upfront):**
  - If it's a **sales agent order**, an email is sent to the customer to complete payment. The customer clicks the link, pays in the **Shopify checkout** and the order is completed in Shopify.
  - Otherwise the customer pays in the **Shopify checkout** and the order is completed in Shopify.
- **Payment on account or by invoice:** the order is completed in SparkLayer ("Order completed (SparkLayer)").
  - If **auto-complete draft orders** is on, a completed order is created in Shopify.
  - If it's off, a draft order is created in Shopify, which becomes a completed order once it's manually marked as complete.

**Can customers use my existing Shopify payment methods?**

Yes, when they choose **Pay Online by Card** in the SparkLayer checkout. This takes them to the Shopify checkout, where the payment methods you've set up in Shopify are available, such as PayPal, Shop Pay or a manual method like bank transfer. Shopify gift cards also only work this way. Each order has one payment method, so a customer can't split an order between, say, card and on account. See [Which payment methods work with the SparkLayer checkout?](https://docs.sparklayer.io/help/ordering/payment-methods.md#which-payment-methods-work-with-the-sparklayer-checkout)

To show B2B customers only some of these methods, see [Hide payment methods in the checkout](https://docs.sparklayer.io/help/platforms/shopify/customisations/payment-methods.md#hide-payment-methods-in-the-checkout).

**Why does my customer see "Pay now" on a Pay on Account order?**

It comes from Shopify, not SparkLayer. Pay on Account orders arrive in Shopify as draft orders with **Payment due later** and payment terms filled in. Once the order is completed, Shopify treats it as an order with a balance to pay, and can show a **Pay now** button on the order status page. Your customer doesn't have to use it: they can pay on their agreed terms. See [Set net payment terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md#set-net-payment-terms).

**Do Shopify vaulted credit cards work with SparkLayer?**

Yes, if you use Shopify Payments and the customer is a contact of a Shopify company (at **Customers > Companies** ([open in the Shopify admin](https://admin.shopify.com/companies))). A card saved by anyone at a company location, at checkout or in their customer account, can be used by every customer at that location. There's nothing to set up in SparkLayer.

- **Pay Online by Card**: the saved cards appear in the Shopify checkout.
- **Pay by Invoice or Pay on Account**: you can charge a saved card on the draft order from your Shopify admin, with **Collect payment**.

See [Use vaulted credit cards](https://docs.sparklayer.io/help/platforms/shopify/companies.md#use-vaulted-credit-cards).

**Can I add a charge to a B2B order based on the payment method?**

Not directly. For example, SparkLayer can't add 2% when a customer pays by credit card.

One workaround is to let the customer order with an offline payment method, such as Pay by Invoice:

1. When the order arrives in Shopify as a draft order, adjust the total.
2. On the draft order, click **Collect payment** and enter the customer's card details to take the payment.

## Orders

**Where do I find B2B orders in Shopify?**

Orders paid by card are regular Shopify orders. Orders paid with other methods (such as Pay by Invoice or Pay on Account) are saved as **draft orders**, and so is a card order the customer didn't finish paying for:

- Find them in your Shopify admin at **Orders > Drafts** ([open in the Shopify admin](https://admin.shopify.com/draft_orders)).
- To ask the customer to pay online, open the draft and click **Send invoice**. See [Send an invoice from a draft order](https://docs.sparklayer.io/help/platforms/shopify/customisations/payment-methods.md#send-an-invoice-from-a-draft-order), or for automatic PDF invoices, [SparkLayer Invoices](https://docs.sparklayer.io/help/ordering/invoices.md) (Growth plan and above).
- To turn a draft into a completed order, mark it as paid or add payment terms. See Shopify's guide to [accepting payment](https://help.shopify.com/en/manual/orders/create-orders#accept-payment).
- To complete draft orders automatically, turn on **Auto-complete draft orders** at **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app.

See [Process orders in Shopify](https://docs.sparklayer.io/help/guides/process-orders-in-shopify.md).

**Why does an order show "Awaiting merchant"?**

It's waiting for you. **Awaiting merchant** means the customer has placed the order in SparkLayer, but it isn't a completed order in Shopify yet: usually it's a Pay on Account or Pay by Invoice order that's still a draft. Complete the draft at **Orders > Drafts** ([open in the Shopify admin](https://admin.shopify.com/draft_orders)), or turn on **Auto-complete draft orders** at **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app. Until then, it shows as **Awaiting merchant** in the SparkLayer **Orders** screen and in your customer's [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md#order-statuses). See [Awaiting merchant](https://docs.sparklayer.io/help/glossary.md#awaiting-merchant).

**Customers see "An unknown error occurred" at checkout. What do I do?**

If the message ends with a code, such as **SHOPIFY:002**, look it up in [Error codes](https://docs.sparklayer.io/help/platforms/shopify/error-codes.md). If there's no code:

1. Refresh the page, or empty the cart and add the products again.
2. Look in **Orders > Drafts** ([open in the Shopify admin](https://admin.shopify.com/draft_orders)) for an open draft order for that customer. Delete it, then try again.
3. Check no product in the order has a price of 0.00 in Shopify, and, if you sell in several currencies, that Shopify Markets has a market for each currency and shipping country.

See [Customers see "An unknown error occurred" at checkout](https://docs.sparklayer.io/help/troubleshooting.md#customers-see-an-unknown-error-occurred-at-checkout) for every check, and what to send us if it keeps happening.

**Why doesn't a draft order I create in Shopify get B2B prices?**

SparkLayer applies B2B prices to orders placed through its cart. A draft order you create yourself in your Shopify admin doesn't go through SparkLayer, so it uses your Shopify prices, unless you change them on the draft. 

To order for a customer at their B2B prices, make yourself or your team sales agents (from the Starter plan) and place the order on your store. See [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md). To show orders made outside SparkLayer in the customer's order history, see [Show imported or manual orders](https://docs.sparklayer.io/help/guides/show-imported-orders.md).

**Can I edit orders?**

Yes. If SparkLayer creates draft orders, you can open a draft order in Shopify and change it. After you complete it by hand (for example with **Mark as paid**), you can still edit it until it's fulfilled.

The exception is when **Auto-complete draft orders** is on at **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app. Because of a Shopify limitation, orders completed this way can't be edited afterwards, and Shopify shows "Unable to edit order". The only fix is to turn off the auto-complete setting.

**Can B2B customers use my Shopify shipping rates?**

Yes. By default, B2B customers see your Shopify shipping, including live carrier rates and shipping apps. From the Starter plan, you can use SparkLayer shipping rates instead, priced by customer group, order total or weight. B2B customers get one or the other, never both: **Use SparkLayer shipping rates** at **Settings > Shipping** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping** in the Shopify app decides. See [Shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md).

If customers see "Sorry, no shipping methods are available for your selected address", see [No shipping methods show at checkout](https://docs.sparklayer.io/help/troubleshooting.md#no-shipping-methods-show-at-checkout).

**Why do B2B prices show as a discount on Shopify orders?**

A line can arrive at its Shopify price with a "Custom discount" that brings it down to your B2B price, so customer emails show the original price struck through. 

- To show only the final price in emails, see [Hide discount pricing](https://docs.sparklayer.io/help/platforms/shopify/customisations/email-notifications.md#hide-discount-pricing).
- To change how prices are sent to Shopify, [contact our team](https://docs.sparklayer.io/help/support.md).
- To change the "Custom discount" wording, go to **Online Store > Themes** ([open in the Shopify admin](https://admin.shopify.com/themes)), click the **...** menu next to your theme, choose **Edit default theme content** and search for "Custom discount".

**Can I set a minimum order quantity?**

Yes. You can set minimum (and maximum) quantities for each product or variant: see [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md). For the whole order, set order limits on a customer group: a minimum or maximum order total, such as $500, or a minimum or maximum number of items. See [Set order limits](https://docs.sparklayer.io/help/storefront/quantity-rules.md#order-limit-rules).

For a product range, one workaround is:

1. Create a new product in Shopify with the products you want to include as its variants.
2. Use the [minimum product quantity](https://docs.sparklayer.io/help/storefront/quantity-rules.md) setting so customers must order at least a set number, for example 3.
3. Use [quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md) to set the discounted rate, for example 10% cheaper when buying 3.

**How do I set up multiple currencies with Shopify Markets?**

Create a Shopify market for each currency, with Shopify Payments active, then a price list in that currency, and assign it to a customer group. SparkLayer doesn't convert prices: you set the exact price in each currency. Shopify's "Use local currencies" setting, duties and market catalogs aren't supported. See [Shopify Markets and currencies](https://docs.sparklayer.io/help/platforms/shopify/markets-and-currencies.md).

**How do I send order notifications to customers and my team?**

Shopify doesn't send a notification when a draft order is created, so you need a workaround.

- **Your team**: import our ready-made **Send an email with order details** workflow into Shopify Flow, a free Shopify app. See [Shopify Flow for B2B](https://docs.sparklayer.io/help/platforms/shopify/customisations/flow.md#email-workflows).
- **Customers**: send a Shopify invoice from the draft order with **Send invoice**.
- **Both**: turn on **Auto-complete draft orders** at **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app, so drafts become completed orders. 

To change Shopify's emails for B2B customers, see [Shopify email notifications](https://docs.sparklayer.io/help/platforms/shopify/customisations/email-notifications.md).

**Can I import historic B2B orders?**

Yes. See [Import order history into SparkLayer](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#import-order-history-into-sparklayer).

**Can I give B2B orders a different order number prefix, such as B2B-123?**

Not in Shopify: it uses one order number sequence (for example #123456) for retail and B2B orders. To tell them apart, use the `b2b` tag SparkLayer adds to every B2B order. You can filter by it in Shopify, and in connected systems such as shipping apps or 3PLs, to separate your workflows. See [Shopify reporting and filtering](https://docs.sparklayer.io/help/platforms/shopify/customisations/reporting-and-filtering.md).

To show customers your own order numbers in their account, see [Set a custom order number](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#set-a-custom-order-number).

## Discounts

**Will my B2B customers get my Shopify discount codes or sales?**

No. Shopify discounts, including discount codes and automatic discounts, don't apply to orders placed through SparkLayer, and can't be used alongside it. To give B2B customers a discount, create it in SparkLayer: see [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md).

**How do I set up B2B discounts and discount codes?**

Use SparkLayer's own [discounts](https://docs.sparklayer.io/help/pricing/discounts.md) at **Pricing > Discounts** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/discounts)), or **SparkLayer Wholesale > Pricing > Discounts** in the Shopify app, on the Growth plan and above, including its 14-day trial. A discount can apply automatically or when the customer enters a coupon code at checkout. You can set requirements such as:

- **An order total or number of items**, for example spend over $400 and get 5% off.
- **Customer groups and dates**, so only some customers get it, for a set time.
- **Products, collections or tags**: under **Rules**, click **New rule**, for example to discount only products tagged `dog-toy`. See [Restrict a discount to certain products](https://docs.sparklayer.io/help/pricing/discounts.md#restrict-a-discount-to-certain-products).

On every plan, you can also give a customer group a percentage off your Shopify prices with an automatic price list.


---

# Limitations

URL: https://docs.sparklayer.io/help/platforms/shopify/limitations
Applies to: Shopify

Check what SparkLayer can't do on Shopify: no Shopify discounts, unique SKUs, a 350-line cart limit, tax and duties handling, app customisations and Companies.

> **Quick summary**
>
> - SparkLayer works on every Shopify plan, but a few Shopify features and setups aren't supported.
> - The ones most stores meet: Shopify discounts can't be used alongside SparkLayer, and every product needs a unique SKU.
> - Carts hold up to 350 line items by default. Our support team can raise this to 500.
> - Duties, prices that include tax, and orders that mix taxable and tax-exempt products need a workaround, often a separate B2B store.

## Limitations and workarounds

Each row explains the limitation and, where there is one, the workaround.

| Limitation | What it means and what to do |
| --- | --- |
| **Discounts** | You can't use Shopify discounts alongside SparkLayer. Use SparkLayer's own [discounts](https://docs.sparklayer.io/help/pricing/discounts.md) for B2B discounts and promotions instead. |
| **Product SKUs** | Every product must have a SKU in Shopify, and each SKU must be unique. |
| **Product customisations from apps** | If an app adds customisations to your products, such as a text-entry field, they don't show in SparkLayer's [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md). SparkLayer only shows the variants in Shopify's own catalogue, such as size and colour. A developer can add customisations with the [JavaScript SDK](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#custom-attributes-and-files), as custom development. |
| **Cart line items** | Carts are limited to 350 line items by default, because of Shopify API performance. On request, our [support team](https://docs.sparklayer.io/help/support.md) can raise this to 500. |
| **Tax-exempt products** | If you use line-item tax exemptions in your product catalogue, SparkLayer can't handle tax correctly on an order that mixes tax-included and tax-exempt products. |
| **Prices that include tax** | If your store is set to include taxes in prices, SparkLayer can't calculate gross prices correctly. We recommend a separate B2B store with this setting off, where SparkLayer can show net prices. |
| **Duties** | Shopify's API doesn't include duties, so SparkLayer can't add them to the cart as a separate charge. If you charge duties, turn them off at **Settings > Taxes and duties** ([open in the Shopify admin](https://admin.shopify.com/settings/taxes/duties/management)), or create a separate B2B store. We'll add support when Shopify makes it available. |
| **Shopify Companies** | Your Shopify B2B companies and locations are kept in sync with SparkLayer both ways, and SparkLayer adds what each one buys at: price lists, payment terms, sales reps and ordering rules. Shopify's own B2B checkout and catalog prices don't run alongside SparkLayer for the same customer: the ordering experience is one or the other. A Shopify catalog still controls which products a company's contacts see: if it leaves a product out, Shopify hides it from them, even when SparkLayer gives them a price. See [Shopify Companies](https://docs.sparklayer.io/help/platforms/shopify/companies.md#limitations). |

## Related limitations

Some limits are covered on other pages:

- Multi-currency limitations, such as Shopify's local currency setting and Managed Markets, are on [Shopify Markets and currencies](https://docs.sparklayer.io/help/platforms/shopify/markets-and-currencies.md#limitations).
- To compare limits across platforms, see [Compare platforms](https://docs.sparklayer.io/help/platforms/compare.md).


---

# Error codes

URL: https://docs.sparklayer.io/help/platforms/shopify/error-codes
Applies to: Shopify

Fix the SHOPIFY:001 to SHOPIFY:007 and PRICING:001 errors in the My Cart interface, caused by Markets currencies, missing SKUs or incomplete customer data.

When SparkLayer can't complete an order, it shows an error code in [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md). Find the code below to see what it means and how to fix it.

## Error codes

| Code | What it means | How to fix it |
| --- | --- | --- |
| **SHOPIFY:001** | The customer's price list is in a currency (for example AUD) that isn't enabled in your Shopify Markets, or the market uses Shopify's setting to show prices in each customer's local currency, which SparkLayer doesn't support. | Turn on the currency in [Shopify Markets](https://docs.sparklayer.io/help/platforms/shopify/markets-and-currencies.md). In a market with several countries or regions, turn off "Show prices to customers in their local currency" for that market. |
| **SHOPIFY:002** | The customer's price list is in a currency (for example AUD), but their shipping country isn't set up in your Shopify Markets. | Add the shipping country to a market in [Shopify Markets](https://docs.sparklayer.io/help/platforms/shopify/markets-and-currencies.md). |
| **SHOPIFY:003** | There's a problem with the product data, such as a variant in the order with no SKU. | Remove the affected product from the order, and add a SKU to the variant in Shopify. |
| **SHOPIFY:005** | The email address on the order fails Shopify's checks, so Shopify won't let the order check out. Shopify uses DNS checks to confirm the email's domain (the part after the @) is real. | Check the email address is valid and spelled correctly, then update it on the customer's record in Shopify. |
| **SHOPIFY:006** | The shipping address is in a country that isn't in any of your store's Shopify Markets. | Make sure every country you ship to belongs to a Shopify market. |
| **SHOPIFY:007** | The customer record is missing an email address, a shipping phone number or a shipping address. Stores using Managed Markets need all three. | Add the missing details to the customer's record in Shopify. |
| **PRICING:001** | The customer's group has two price lists in different currencies (for example GBP and USD). | 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 edit the group, so all its price lists use one currency. |

If you see an error that isn't listed here, or the fix doesn't work, [contact our support team](https://docs.sparklayer.io/help/support.md) with the error code.


---

# Cancel, uninstall or transfer SparkLayer

URL: https://docs.sparklayer.io/help/platforms/shopify/uninstall
Applies to: Shopify

Cancel SparkLayer on Shopify by uninstalling the app, see what happens to billing and your data, move SparkLayer to another store or extend your trial.

> **Quick summary**
>
> - To cancel SparkLayer, uninstall **SparkLayer Wholesale** at **Settings > Apps and sales channels** ([open in the Shopify admin](https://admin.shopify.com/settings/apps)) in your Shopify admin. This ends your subscription, and SparkLayer billing stops straight away.
> - Treat uninstalling as deleting your SparkLayer data. Export anything you need first, such as your price lists. The frontend code in your theme isn't removed for you.
> - Planning to reinstall, move to another Shopify store or try changes on a test store? [Contact our team](https://docs.sparklayer.io/help/support.md) before you uninstall.
> - For plans, downgrading and refunds, see [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md). To extend your free trial, [contact our team](https://docs.sparklayer.io/help/support.md).

## Before you uninstall

If SparkLayer isn't right for you just now, we'd like the chance to help first. Tell us the main reason you're thinking of cancelling:

- [It's too expensive](https://www.sparklayer.io/feedback/?reason=pricing)
- [I'm not using it enough](https://www.sparklayer.io/feedback/?reason=usage)
- [It's missing features I need](https://www.sparklayer.io/feedback/?reason=features)
- [I'm having technical issues](https://www.sparklayer.io/feedback/?reason=technical)
- [I'm switching to a competitor](https://www.sparklayer.io/feedback/?reason=competitor)
- [It's something else](https://www.sparklayer.io/feedback/?reason=other)

> **Uninstalling deletes your SparkLayer data**
>
> Treat uninstalling as deleting your SparkLayer account: its price lists, customer groups and settings. Before you uninstall, export anything you want to keep, such as your [price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md). If you plan to reinstall, [transfer to another store](#transfer-sparklayer-to-another-shopify-store) or need a [test store](https://docs.sparklayer.io/help/dashboard/test-mode.md), [contact our support team](https://docs.sparklayer.io/help/support.md) first, so we can talk through your options. Don't uninstall to change your plan: see [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md).

## Uninstall SparkLayer

SparkLayer works as a sales channel in Shopify, called **SparkLayer Wholesale**. You remove it like any other sales channel.

1. In your Shopify admin, go to **Settings > Apps and sales channels** ([open in the Shopify admin](https://admin.shopify.com/settings/apps)).
2. On the **Installed** tab, find **SparkLayer Wholesale**, open its **...** menu and click **Uninstall**. 
3. Optionally, enter a reason for removing the channel.
4. Confirm the uninstall.

Shopify's guide to [removing a sales channel](https://help.shopify.com/en/manual/online-sales-channels#remove-an-online-sales-channel-from-your-shopify-admin) has more detail.

### What happens when you uninstall

Uninstalling affects your billing, your SparkLayer account and your theme:

| What | What happens |
| --- | --- |
| **Billing** | Your subscription ends, and SparkLayer's recurring charges are cancelled straight away. Depending on when your billing cycle started, you may still see charges you weren't expecting. See [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md) for refunds, or [contact us](https://docs.sparklayer.io/help/support.md) and we'll look into them. |
| **Your SparkLayer account and data** | Scheduled for deletion, and deleted automatically 30 days after you uninstall. Until then, a warning at the top of the SparkLayer Dashboard tells you the account is scheduled for deletion. Don't rely on getting your data back: export it before you uninstall. |
| **Frontend code in your theme** | Not removed. If you added the SparkLayer [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) to your theme, remove them by hand, or ask your developer. They only show to signed-in B2B customers, so they don't affect retail visitors in the meantime. |

## Transfer SparkLayer to another Shopify store

When you sign up, your SparkLayer account is linked to one Shopify address, for example `storename.myshopify.com`. SparkLayer is then locked to that store: it syncs its products and customers, and you install the frontend code there.

You might want to move SparkLayer to another store if:

- You tried SparkLayer on a **test or development store** and now want to use it on your live store.
- You're moving from a hybrid store (retail and B2B together) to a standalone B2B store, or the other way round.

A transfer starts with uninstalling SparkLayer from the old store, which deletes its SparkLayer data. So before you start, [contact our support team](https://docs.sparklayer.io/help/support.md), and export anything you want to keep, such as your [price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md).

To transfer your account:

1. Sign in to your current Shopify store and [uninstall SparkLayer](#uninstall-sparklayer). This disconnects SparkLayer from that store.
2. Create a new team: see [Account settings](https://docs.sparklayer.io/help/dashboard/account.md).
3. [Sign in to the SparkLayer Dashboard](https://app.sparklayer.io/Login) with the new team and 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.
4. Under **Your platform**, select **Shopify** and enter the address of the new store in **Shopify store**, for example `new-storename`. 
5. Shopify opens and asks you to install **SparkLayer Wholesale** and choose a plan.
6. You're returned to SparkLayer, which starts syncing the new store's products and customers. Then work through **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app for the new store, including [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md).

The transfer doesn't move any Shopify data, such as products, customers or orders. Move that separately, for example with an app like [Matrixify](https://apps.shopify.com/excel-export-import). If you'd like help, [contact us](https://docs.sparklayer.io/help/support.md).

## Extend your trial

When you first set up SparkLayer, you get a free trial, so you can check it's a good fit. If you need more time, [contact our team](https://docs.sparklayer.io/help/support.md) and we'll talk it through.


---

# Shopify customisations

URL: https://docs.sparklayer.io/help/platforms/shopify/customisations
Applies to: Shopify

Customise your Shopify B2B store with SparkLayer: login and registration, B2B-only content, Shopify Flow, payments, emails, reporting and landing pages.

> **Quick summary**
>
> - These guides are optional extras. Once SparkLayer is [installed](https://docs.sparklayer.io/help/platforms/shopify/install.md), B2B customers can sign in and order straight away.
> - Most are changes to your Shopify store or theme, often with Liquid (Shopify's theme code). If you're not comfortable editing theme code, pass these guides to your developer or a Shopify expert.
> - Start by deciding whether to run B2B in your retail store or a separate one, then add a B2B login and registration page.

## Customisation guides

The guides run roughly in the order most stores need them.

- [One store or a separate B2B store](https://docs.sparklayer.io/help/platforms/shopify/customisations/store-setup.md): Choose between one hybrid retail and B2B store or a separate B2B store
- [B2B registration and login](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md): Add a B2B login page, take account applications and make customers sign in
- [B2B-only content](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-only-content.md): Hide products and prices, and show B2B-only menus, banners and content
- [B2B landing page](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-landing-page.md): Send B2B customers to a landing page of your choice when they sign in
- [Shopify payment methods](https://docs.sparklayer.io/help/platforms/shopify/customisations/payment-methods.md): Handle offline payments as draft orders and control checkout payment methods
- [Email notifications](https://docs.sparklayer.io/help/platforms/shopify/customisations/email-notifications.md): Show B2B-specific content in Shopify emails and customise account invites
- [Shopify Flow for B2B](https://docs.sparklayer.io/help/platforms/shopify/customisations/flow.md): Ready-made workflows to automate B2B orders, customers, products and emails
- [Reporting and filtering](https://docs.sparklayer.io/help/platforms/shopify/customisations/reporting-and-filtering.md): Report on B2B sales by sales channel, order tag and order attributes


---

# One store or a separate B2B store

URL: https://docs.sparklayer.io/help/platforms/shopify/customisations/store-setup
Applies to: Shopify

Decide between running B2B and retail from one Shopify store or a separate B2B store, what to check for each, and how to set up and sync an additional store.

> **Quick summary**
>
> - You can add B2B to your existing Shopify store (a hybrid store) or set up a new, standalone Shopify store just for B2B.
> - In a hybrid store, B2B and retail orders share the same stock, and you'll need to check your apps, reporting and tracking pixels.
> - A separate store keeps B2B stock, products, integrations and web address apart. You install SparkLayer on it too, and sync data between stores with an app.

## How it works

When you set up B2B on Shopify, you have 2 options:

1. **Hybrid store**: turn on B2B in your **existing** Shopify store, so retail and B2B customers use the same store.
2. **Standalone store**: set up a **new** Shopify store just for B2B.

![Diagram of a hybrid store: retail (B2C) and B2B on one Shopify store at the same web address](https://docs.sparklayer.io/images/help/integrations/shopify/customisations/store-setup/store-setup-d5e6d4.webp)

Both have advantages and drawbacks, and which suits you is a business decision. With SparkLayer you don't need to duplicate your store, but check the points below first.

## Check before you go hybrid

Before you add B2B to your retail store, check how it affects these areas:

- **Stock and warehouses.** You can't send B2B orders from specific stock locations when they go through the Shopify checkout. In a hybrid store, B2B orders share the same stock pool as retail, which can affect stock allocation. Think through the impact carefully.
- **Your apps.** Check whether any installed apps could interfere with B2B, such as apps that send "leave a review" emails or other post-purchase follow-ups. Many let you exclude customers by tag, and every SparkLayer customer has the `b2b` tag.
- **Analytics and reporting.** SparkLayer appears in Shopify as a sales channel called **SparkLayer Wholesale**, so you can segment reports and orders by that channel. See [Shopify reporting and filtering](https://docs.sparklayer.io/help/platforms/shopify/customisations/reporting-and-filtering.md).
- **Affiliate and tracking pixels.** Your store and checkout may have tracking code that records sales. Exclude B2B customers from it, for example by filtering out customers tagged `b2b`. This usually needs a Shopify developer. See Shopify's guide to [adding additional scripts to the order status page](https://help.shopify.com/en/manual/orders/status-tracking/customize-order-status#add-additional-scripts).

## Set up a separate B2B store

If a hybrid store doesn't suit you, set up a separate Shopify store for B2B. You can automate much of the setup. The most common reasons to create one are:

- **Stock**: you need to keep B2B stock separate from retail.
- **Products**: you want a completely different product catalogue for B2B customers.
- **Integrations**: you need to connect your B2B channel to a different system from your retail channel.
- **Web address**: you need a separate address for B2B, such as `b2b.yourstore.com`.

We recommend this approach:

1. **Set up your main B2B store.** Install SparkLayer, then configure and customise the store as you need, for example its theme, homepage and product pages.
2. **Copy your theme.** You'll probably want your stores to look the same, so export the theme from your main B2B store and import it into each additional store. Shopify's guide to [downloading themes](https://help.shopify.com/en/manual/online-store/themes/managing-themes/downloading-themes) explains how.
3. **Install SparkLayer on each additional store**, as you did on your main store. We're happy to help, and to discuss a combined pricing rate.
4. **Sync your data.** Set up a way to keep data in step between your stores, such as products, content and even orders. We recommend two Shopify apps: [Matrixify](https://apps.shopify.com/excel-export-import) and [Syncio](https://apps.shopify.com/syncio).

You'll probably need someone with Shopify expertise to help, and we're happy to advise where we can. If you've already installed SparkLayer on one store and want to move it, see [Transfer SparkLayer to another Shopify store](https://docs.sparklayer.io/help/platforms/shopify/uninstall.md#transfer-sparklayer-to-another-shopify-store).


---

# B2B registration and login

URL: https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login
Applies to: Shopify

Add a B2B login and registration page to Shopify, choose how account applications work, translate it, make customers sign in and add a B2B onboarding page.

> **Quick summary**
>
> - Our free, ready-made B2B login page (at `/pages/b2b-login`) lets existing customers sign in and new ones apply for an account. You customise it in the Shopify theme editor, and our team can install it for you free of charge.
> - Applications can email you through Shopify's contact form, use an embedded form (such as a [SparkLayer form](https://docs.sparklayer.io/help/forms.md)), or go to a page of your choice.
> - For approval workflows and automatic customer tagging, use [SparkLayer Forms](https://docs.sparklayer.io/help/forms.md) for registration.
> - With a small theme code change (for your developer), you can make customers sign in before they see your store.

## How it works

On Shopify, SparkLayer uses Shopify's own sign-in at `/account`, for example `www.yourstore.com/account`. Customers sign in with their email and password on Legacy customer accounts, or with a one-time code on new customer accounts. See [Choose your customer accounts version](https://docs.sparklayer.io/help/platforms/shopify/install.md#choose-your-customer-accounts-version).

Your retail customers use the same sign-in page, so you may want to send B2B customers to a dedicated B2B page instead.

Registration lets prospective customers apply for a B2B account, usually with a review step so you can check their details before giving them access. A typical flow:

From application to first order:

1. **Customer applies**: They fill in the application form on your B2B login page
2. **You review**: You check the application and create or approve the customer
3. **Give access**: Tag them `b2b` in Shopify, or invite them with **Invite a buyer**, which tags them for you
4. **Customer signs in**: They sign in on the B2B login page and start ordering

## Add the B2B login page

The ready-made page has a sign-in form (**Email**, **Password**, **Sign in** and a forgotten password link), a section inviting new customers to apply for an account, and an optional set of questions and answers. Once it's set up, customers go to `/pages/b2b-login` to sign in or apply.

Our team is happy to set this page up for you, free of charge: [contact us](https://docs.sparklayer.io/help/support.md). Step 1 below adds files to your theme code, so if you don't edit theme code yourself, ask us or your developer. To do it yourself, follow the steps.

**Step 1.** **Add the code to your theme**

Create two new files in your Shopify theme code:

1. In the `/sections/` folder, create `main-b2b-login.liquid` and [add this code](https://gist.github.com/cm-sl/c725a1de3c926257f9f81ee5fc70a029).
2. In the `/templates/` folder, create `page.b2b-login.json` and [add this code](https://gist.github.com/cm-sl/1c18244e75ed401b217f15eb1c9d6308).

To change how the page works later, edit these files in your theme.

**Step 2.** **Create the page in Shopify**

1. In your Shopify admin, go to **Online Store > Pages** ([open in the Shopify admin](https://admin.shopify.com/pages)) and click **Add page**.
2. Enter the title **B2B Login**.
3. Under **Search engine listing**, check the **URL handle** is `b2b-login` (Shopify usually sets this automatically).
4. Under **Template**, choose `b2b-login`, then save.

**Step 3.** **Customise and check the page**

1. Go to **Online Store > Themes** ([open in the Shopify admin](https://admin.shopify.com/themes)) and click **Customize**.
2. Open the `b2b-login` page from the page selector at the top, and select the **Login Page** section. You can change nearly everything, including colours, form fields and text, such as the **Title**, **Introduction Text** and **Open Account Title**.
3. Visit `www.yourstore.com/pages/b2b-login` to see the new page.

## Choose how applications work

Once the page is live, choose what happens when someone applies for an account. In the theme editor, the **Login Page** section has a **Form Action** setting for this. Go to **Online Store > Themes** ([open in the Shopify admin](https://admin.shopify.com/themes)), click **Customize**, open the `b2b-login` page and choose an option:

| Form Action | What happens |
| --- | --- |
| **Send an email to the store owner** | The application is emailed to your Shopify store's email address, using Shopify's contact form. |
| **Embed custom contact form** | You paste in the HTML for another form, such as a [SparkLayer form](#embed-a-sparklayer-form) or a third-party form app. |
| **Go to new page URL** | Customers are sent to another page, such as an existing application form on your store or another website. |

### Send an email to the store owner

The application form uses Shopify's [built-in contact form](https://help.shopify.com/en/manual/online-store/themes/os/customize/add-contact-form). By default it asks for **Name**, **Email**, **Phone number**, **Company**, **Website** and **Comment**. When someone sends it, Shopify emails your store's email address with every field they filled in. The subject is usually "New customer message on \[date of submission]".

To add a field:

1. In the theme editor, under the **Login Page** section, click **Add block**.
2. Choose **Form Field**.
3. Enter the field's name and the default text to show.

Sending the form doesn't create a customer in Shopify. When you've reviewed the application, add the customer in Shopify with the `b2b` tag and their customer group's tag. See [Add B2B customers on Shopify](https://docs.sparklayer.io/help/platforms/shopify/invite-customers.md). Or invite them with **Invite a buyer** at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app, which adds them to Shopify with the tags for you. See [Invite a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md).

Occasionally, Shopify's contact form doesn't deliver emails, for example if your recipient address is bouncing or being blocked by Shopify. If that happens, contact Shopify Support and tell them your store's [contact form](https://help.shopify.com/en/manual/online-store/themes/customizing-themes/add-contact-page) isn't working as expected.

### Embed a SparkLayer form

To manage applications with a [SparkLayer form](https://docs.sparklayer.io/help/forms.md) instead of the Shopify contact form, embed it in your B2B login page.

1. In the SparkLayer Dashboard, go to **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)), open your form and go to its **Embed** tab. Forms aren't in SparkLayer Wholesale. Copy the HTML embed code.  It looks like this:

   ```html
   <spark-form form-id="your-form-id" site-id="your-site-id"></spark-form><script src="https://cdn.sparklayer.io/spark-form.v1.0.0.js"></script>
   ```

2. In your Shopify admin, go to **Online Store > Themes** ([open in the Shopify admin](https://admin.shopify.com/themes)), click **Customize** and open your B2B login page.

3. Set **Form Action** to **Embed custom contact form**, and paste the code into **Custom Contact Form HTML**.

4. Save, then visit the page to check the form shows and works.

Build and customise your form at **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)). See [SparkLayer Forms](https://docs.sparklayer.io/help/forms.md) to learn more.

### Embed a custom contact form

To use another form, such as one from a form app:

1. In the theme editor, set **Form Action** to **Embed custom contact form**.
2. Paste your form's HTML code into **Custom Contact Form HTML**, then save.

### Go to a new page URL

To send applicants to another page instead of showing a form, for example an existing registration page on your store or on another website:

1. In the theme editor, set **Form Action** to **Go to new page URL**.
2. Enter the address in **Redirect URL**, then save.

## Use SparkLayer Forms for registration

For more control over registration, use SparkLayer Forms, our built-in, no-code form builder. You manage registration forms in SparkLayer, with no third-party apps. With SparkLayer Forms, you can:

- Build forms with a drag-and-drop builder and field types such as text, email, drop-downs, file uploads and addresses.
- Review and approve applications before giving access.
- Tag customers automatically, assign them to customer groups and sync their data to your platform.
- Start quickly with the ready-made **Customer Registration Form** template.

You handle the whole process, from application to approval and creating the customer, in one place. See [SparkLayer Forms](https://docs.sparklayer.io/help/forms.md).

## Translate the B2B login page

If your store uses Shopify Markets to show different languages by location, you can translate the B2B login and registration page. First, check Shopify Markets is set up with a language for each target market, for example French for France and German for Germany.

We recommend Shopify's own [Translate & Adapt app](https://apps.shopify.com/translate-and-adapt), which shows translations side by side with your original content.

1. Install and open **Translate & Adapt**.
2. At the top, choose the language you want to edit.
3. Under **Theme**, click **Templates**.
4. In the list, select the B2B login page. It's usually called **Page: B2B Login**, unless you renamed the page.
5. Translate each field on the right: type your translations, or click **Auto-translate** (if it's available) to have Shopify translate every field.
6. Save.

This translates the page's own text, such as its title and introduction. It doesn't translate the fields of an embedded [SparkLayer form](#embed-a-sparklayer-form): the form loads as an embed, which Translate & Adapt can't reach. Instead, make one form per language and paste each one's embed code into the **Main: Custom Form Html** field for that language. See [Translate a form](https://docs.sparklayer.io/help/forms/embedding-and-styling.md#translate-a-form).

## Make customers sign in before they see your store

To lock your whole store until a customer signs in, add code to your theme's `theme.liquid` file. This is a theme code change, so pass this section to your developer if you don't edit theme code yourself. The example below works like this:

1. Signed-out visitors are sent to the account login page, `/account/login`.
2. Customers' account pages, the Shopify Customizer and a few pages you choose (such as `/pages/b2b-login` and `/pages/contact-us`) are left open.
3. Signed-in B2B customers see the whole store as normal.

Add the code to `theme.liquid` before the closing `</head>` tag, and change the list of open pages to suit your store:

```html
<!-- Add this code to theme.liquid before the closing head tag
template refers to files within your theme
request.path refers to URLs on your store
-->

 {%- if customer.metafields.sparklayer.authentication -%}
 <!-- Don't redirect for B2B customers -->

{%- else -%} 

{%- if request.design_mode -%}

<!-- Don't redirect if using Shopify Customiser tool -->

{%- else -%} 

   {%- if template contains 'customers/' 
      or request.path == '/challenge' 
      or request.path == '/pages/contact-us' 
      or request.path == '/pages/b2b-login' 
      or request.path == '/pages/about-us' 
      or request.path == '/pages/terms-and-conditons' 
     -%}

     <!-- Do nothing -->

   {%- else -%}

     <script>
       window.location.href = '/account/login';
     </script>

   {%- endif -%}

{%- endif -%}

{%- endif -%} 

<!-- End of redirect code -->
```

## Wholesale-only stores: customers who sign in without a trade account

With Shopify's new customer accounts, anyone can sign in to your store with a code sent to their email. Shopify gives them a customer account, without them applying for one. SparkLayer only loads for customers tagged `b2b`, so a signed-in customer without the tag sees your store as a retail shopper would. If you [hide prices from signed-out visitors](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-only-content.md#hide-prices-from-signed-out-visitors), prices can flicker for them, because they're signed in but aren't B2B customers.

The same happens when a B2B customer signs in with a mistyped or different email address: Shopify creates a new retail customer with no `b2b` tag. Ask them to sign out and sign in with the email you invited. With Legacy customer accounts, customers must activate their account from the invite email before they can sign in.

On a wholesale-only store, choose one of these options:

| Option | How it works |
| --- | --- |
| **1. Switch back to Legacy customer accounts** | Customers need a password to sign in, so an emailed code isn't enough to get an account. We don't recommend it, because Shopify doesn't fully support Legacy accounts. See [Choose your customer accounts version](https://docs.sparklayer.io/help/platforms/shopify/install.md#choose-your-customer-accounts-version). |
| **2. Redirect them to a page** | Keep new customer accounts, and send signed-in customers without a trade account to a page that says they need a wholesale account. |
| **3. Show them a banner** | Keep new customer accounts, and show signed-in customers without a trade account a banner that links to your [application form](#choose-how-applications-work). |
| **4. Sign them out** | Keep new customer accounts, sign these customers out, and show a message on the login page. |

Our team can set up the banner or the redirect for you: [contact us](https://docs.sparklayer.io/help/support.md). Options 2 to 4 are theme code changes, so if you'd rather do them yourself, pass this section to your developer.

**Code for your developer**

These options use the same check as the rest of this page: a signed-in customer without the `customer.metafields.sparklayer.authentication` metafield isn't a B2B customer. For example, this redirects them to a page with the handle `wholesale-account-needed`. Add it to `theme.liquid` before the closing `</head>` tag:

```html
{%- if customer and customer.metafields.sparklayer.authentication == blank -%}
  {%- unless request.path == '/pages/wholesale-account-needed' or template contains 'customers/' -%}
    <script>
      window.location.href = '/pages/wholesale-account-needed';
    </script>
  {%- endunless -%}
{%- endif -%}
```

For a banner instead, use the same condition around the banner code in [Show a B2B-only banner](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-only-content.md#show-a-b2b-only-banner), with a link to your application form.

## Add a B2B onboarding page

An onboarding page explains the benefits of your new B2B store to customers, and encourages them to use it. Our ready-made page has a welcome heading, a picture of the B2B cart and account area, and a list of what customers can do, such as viewing their order history, tracking orders, downloading invoices, updating addresses and seeing reports.

1. In your Shopify admin, go to **Online Store > Pages** ([open in the Shopify admin](https://admin.shopify.com/pages)) and click **Add page**.
2. In the **Content** editor, click **Show HTML** (the `</>` button) and paste in the [onboarding page code from this gist](https://gist.github.com/cm-sl/47d750425f90d527e1210efe3735dc7f).
3. Change the title, content and URL as you need. We recommend the URL handle `b2b-onboarding`, set under **Search engine listing**.
4. Under **Visibility**, choose **Visible** to publish the page, then save. Click **View** to see it.
5. Link to the page from your store, for example in your header or footer navigation, or from your B2B login page.

## Invite and activate B2B customers

To invite B2B customers and activate their accounts, see the [launch checklist](https://docs.sparklayer.io/help/get-started/launching.md). To change the activation emails they receive, see [Shopify email notifications](https://docs.sparklayer.io/help/platforms/shopify/customisations/email-notifications.md#b2b-customer-account-invite-email).

## FAQs

**Where do I find my B2B login page?**

Go to `/pages/b2b-login` on your store, for example `www.yourstore.com/pages/b2b-login`. In your Shopify admin, it's listed with your other pages under **Online Store > Pages** ([open in the Shopify admin](https://admin.shopify.com/pages)). If it isn't there, it hasn't been added yet: see [Add the B2B login page](#add-the-b2b-login-page), or ask our team to add it for you.

**How do I approve a wholesale application?**

Review the application, then add the customer in Shopify with the `b2b` tag and their customer group's tag (see [Add B2B customers on Shopify](https://docs.sparklayer.io/help/platforms/shopify/invite-customers.md)), or invite them with **Invite a buyer** at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app. With **Send an email to the store owner**, each application arrives as a registration email at your Shopify store's email address. An application doesn't create a customer in Shopify on its own: inviting them adds them to Shopify with their customer group's tag. See [Invite a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md).

To review and approve applications in one place, with automatic tagging, use [SparkLayer Forms](#use-sparklayer-forms-for-registration) instead of the contact form.

**Is the B2B login page part of the SparkLayer app?**

No. The example login and registration page is standard Shopify code: Liquid and CSS written to Shopify's best practice. Any Shopify developer can change it.

**Who supports the built-in registration form?**

The built-in form uses Shopify's standard contact form system. It's no different from adding a contact page to your store, so it's supported by Shopify rather than SparkLayer.

**What happens if a customer enters the wrong email or password?**

The page redirects to Shopify's standard login page, which tells the customer their details are incorrect. With new customer accounts, a mistyped or different email signs them in as a new retail customer without the `b2b` tag, so they don't see SparkLayer. See [Wholesale-only stores](#wholesale-only-stores-customers-who-sign-in-without-a-trade-account).

**Someone signed in without applying. Why do they have an account?**

With Shopify's new customer accounts, anyone can sign in with an emailed code and get a Shopify customer account. They don't see SparkLayer unless they're tagged `b2b`. See [Wholesale-only stores](#wholesale-only-stores-customers-who-sign-in-without-a-trade-account) for your options.


---

# B2B-only content

URL: https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-only-content
Applies to: Shopify

Show or hide Shopify content for B2B customers: B2B-only products, hidden prices, B2B content, metafields, menus and banners, and redirects by customer type.

> **Quick summary**
>
> - To show products only to B2B customers, use [B2B Catalogs](https://apps.shopify.com/sparklayer-b2b-catalogs), a free SparkLayer app for Shopify. No code needed.
> - For everything else (hidden prices, B2B-only content, menus, banners and redirects), add Liquid code to your theme that checks whether the customer is a signed-in B2B customer.
> - These are theme code changes. We can explain the approach, but we can't make the changes for you, so we recommend working with a Shopify expert.

## How it works

Your theme can check who's browsing and show different content to B2B customers. The examples on this page use 2 checks:

| Check | When it's true |
| --- | --- |
| `customer.tags contains 'b2b'` | The signed-in customer has the `b2b` tag in Shopify. |
| `customer.metafields.sparklayer.authentication` | The customer is signed in as a SparkLayer B2B customer. |

Wrap content in one of these `{% if %}` checks to show it only to B2B customers, or put it in the `{% else %}` part to show it only to everyone else.

## Show products only to B2B customers

If you run B2B and retail in one Shopify store, you may have products that only signed-in B2B customers should see and buy, such as high-volume or B2B-exclusive lines.

[B2B Catalogs](https://apps.shopify.com/sparklayer-b2b-catalogs) is a free SparkLayer app that controls which products each type of customer can see. You can hide products from retail customers, make products B2B-only, or show different ranges to different customer groups, all with tags and no code.

[Install B2B Catalogs](https://apps.shopify.com/sparklayer-b2b-catalogs) from the Shopify App Store, then follow the [B2B Catalogs documentation](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md) to set it up. To hide variants from particular customer groups, see [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md).

## Hide prices from signed-out visitors

On a dedicated B2B (wholesale-only) store, you can hide prices from anyone who isn't signed in. Logged-out visitors and guests, and customers without the `b2b` tag, see your normal Shopify (retail) prices, because SparkLayer only shows B2B prices to signed-in B2B customers. To stop prices being visible to the public, add code like the example below to:

- **Product cards** on your collection pages (for example `/collections/all`). The code is usually in the `/snippets/` folder, for example `/snippets/card-product.liquid`.
- **The product page.** This is usually in the `/sections/` folder, for example `/sections/main-product.liquid`.

The code shows the SparkLayer product card to signed-in B2B customers, and a "Please sign in to see pricing" message to everyone else:

```html
{%- if customer.metafields.sparklayer.authentication -%}

<!-- B2B content here -->
<spark-product-card parent-id="{{ product.id }}"></spark-product-card>

{%- else -%}

  <div style="font-size: 14px; position: relative; z-index: 10">
    Please 
    <a href="/account/login?return_url={{ request.path }}" style="color: #000; text-decoration: underline">sign in</a> to see pricing
  </div>
  <style>
    [data-spark="b2c-only"] { display:none !important; }
  </style>

{%- endif -%}
```

## Show content only to B2B customers

You can show or hide any content depending on who the customer is, such as extra links in the navigation, or content on your homepage or product pages.

```html
{% if customer.tags contains 'b2b' %}

    Show this content to logged-in B2B customers

{% else %}

    Show this content to logged-out customers

{% endif %}
```

## Show B2B-only product information

You can store extra wholesale information against each product, such as barcodes or marketing content, in Shopify [metafields](https://docs.sparklayer.io/help/platforms/shopify/metafields.md). Then show it only to B2B customers, for example in an "Additional information" box on the product page.

This example lists a product's metafields, but only to signed-in customers tagged `b2b`:

```html
{% if customer.tags contains 'b2b' %}

  {%assign custom_attributes = product.metafields.products %}

  {%if custom_attributes.size > 0 %}  

  <div class="product-meta">
    <p><strong>Additional wholesale information:</strong></p>
    <ul>
      {% for field in custom_attributes %}
        {% assign attribute_code = field | first %}
        {% assign attribute_value = field | last %}
        <li class="custom-attribute-item">
        <span class="custom-attribute-name">{{ attribute_code }}</span>: 
        <span class="custom-attribute-value">{{attribute_value}}</span> 
        </li>
      {% endfor %}
    </ul>
    </div>
  {%endif%}

{% endif %}
```

To show a single SparkLayer metafield on a collection or product page, such as the pack size:

```html
<!-- Only show this to logged in B2B customers -->

{% if customer.tags contains 'b2b' %}

  {% if product.metafields.sparklayer.pack_size %}

    <!-- In this example, we're outputting the pack size -->
    Pack size: {{ product.metafields.sparklayer.pack_size }}

  {% endif %}

{% endif %}
```

See [Shopify metafields and data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md) to set metafields up, and Shopify's [metafields guide](https://help.shopify.com/en/manual/custom-data/metafields) to learn more about them.

## Show a B2B-only navigation menu

You can show signed-in B2B customers a different menu, using Shopify's own menus. If you use our [Shopify B2B Dawn theme](https://docs.sparklayer.io/help/platforms/shopify/dawn-theme.md), it has a B2B menu built in.

By default, a menu with the handle `b2b-menu` also sets the collections buyers can filter Catalog and Quick Order by. See [Collections in Catalog and Quick Order](https://docs.sparklayer.io/help/platforms/shopify/catalog-collections.md).

**Step 1.** **Create the menu**

In your Shopify admin, go to **Online Store > Navigation** ([open in the Shopify admin](https://admin.shopify.com/menus)) and create a menu. Note its **Handle**, for example `b2b-menu`.

**Step 2.** **Update your header code**

Find the Liquid file that builds your menu, usually `/sections/header.liquid`. Look for a line like this:

`{%- for link in menu.links -%}`

Replace it with the code below, changing `b2b-menu` to your menu's handle:

```javascript
{%- if customer.metafields.sparklayer.authentication -%}
{% assign menu = linklists.b2b-menu %}
{%- else -%}
{% assign menu = linklists.main-menu %}
{%- endif -%}
{%- for link in menu.links -%}
```

In the Shopify B2B Dawn theme, edit these files instead:

- `/snippets/header-drawer.liquid`
- `/snippets/header-dropdown-menu.liquid`
- `/snippets/header-mega-menu.liquid`

**Step 3.** **Repeat for the footer (optional)**

Do the same for your footer if you want it to change for signed-in B2B customers too.

## Show a B2B-only banner

A banner that only signed-in B2B customers see can confirm they're getting wholesale prices, or link to bulk ordering. This example shows a dark bar above your header with a **B2B Partner** badge, a welcome message and a **Shop Wholesale** link.

Add it to `layout/theme.liquid` for a banner on every page, or to `sections/header.liquid`:

```html
{% if customer and customer.tags contains 'b2b' %}
    <style>
    .b2b-banner-premium {
        background: linear-gradient(90deg, #1a1a1a 0%,rgb(35, 35, 35) 100%);
        color: #fff;
        padding: 10px 20px;
        text-align: center;
        font-family: 'Inter', sans-serif;
        font-size: 14px;
        letter-spacing: 0.5px;
        display: flex;
        justify-content: center;
        align-items: center;
        gap: 10px;
    }
    .b2b-banner-premium .badge {
        background: #fff;
        color:rgb(50, 50, 50);
        padding: 2px 8px;
        border-radius: 4px;
        font-weight: 900;
        font-size: 11px;
        text-transform: uppercase;
    }
    .b2b-banner-premium a {
        color: #fff;
        font-weight: bold;
        margin-left: 15px;
        text-decoration: none;
        border-bottom: 1px dotted #fff;
        transition: opacity 0.2s;
    }
    .b2b-banner-premium a:hover { opacity: 0.8; }
  </style>

  <div class="b2b-banner-premium">
    <span class="badge">B2B Partner</span>
    <span>Welcome back! You are accessing <strong>Exclusive Wholesale Pricing.</strong></span>
    <a href="/collections/all">Shop Wholesale →</a>
  </div>
 {%- endif -%}
```

## Hide content from B2B customers with CSS

You can also do the opposite, and hide content from B2B customers. One way is CSS that only loads when a B2B customer is signed in:

```css
{%- if customer.metafields.sparklayer.authentication -%}
<style>
.element-name {
display: none !important;
}
</style>
{%- endif -%}
```

Content hidden with CSS still loads on the page, so anyone can find it in the page source, including search engines.

## Change the Core Script by customer tag

You can change how SparkLayer behaves for different customers with logic in the SparkLayer Core Script. For example, you might show a [custom checkout field](https://docs.sparklayer.io/help/ordering/checkout-fields.md) only to customers with a particular tag. Start from this example:

```javascript
<!-- SparkLayer core script code -->
{% for tag in customer.tags %}

{% if tag == "b2b-group-1" %}
   -- Code in here for group-1 --

{% elsif tag == "b2b-group-2" %}
    -- Code in here for group-2--

{% else %}
    -- Code in here as fallback --
{% endif %} 

{% endfor %}

<!-- SparkLayer core script code -->
```

## Redirect B2B customers from a page

You can send signed-in B2B customers from one page to another: for example, from your homepage (the `index` template) to a B2B collection such as `/collections/b2b`.

Add this to `layout/theme.liquid` before the closing `</head>` tag, and change the pages to suit your store:

```javascript

{%- if customer.metafields.sparklayer.authentication -%}

 {%- if template contains 'index' 
      or request.path == '/index' 
      or request.path == '/pages/your-specific URL' 
     -%}

   <script>
       window.location.href = '/collections/all';
   </script>

   {%- endif -%}

{%- endif -%}
```

To choose where B2B customers land when they sign in, see [Shopify B2B landing page](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-landing-page.md).

## Redirect signed-out visitors from a page

To block pages for anyone who isn't a signed-in B2B customer, redirect them elsewhere. Add this to `layout/theme.liquid` before the closing `</head>` tag, and change the paths to suit your store:

```javascript

{%- if customer.metafields.sparklayer.authentication -%}
<!-- Do nothing for logged in B2B customers -->
{%- else -%}

{%- if  request.path == '/path-to-page-here' or request.path == 'path-to-another-page-here' -%}

   <script>
   window.location.href = '/url-to-redirect-to';
   </script>
{%- endif -%}
{%- endif -%}
```

To lock your whole store until customers sign in, see [Make customers sign in before they see your store](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md#make-customers-sign-in-before-they-see-your-store).


---

# B2B landing page

URL: https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-landing-page
Applies to: Shopify

Send Shopify B2B customers to a landing page of your choice when they sign in: a B2B collection, a custom Shopify page or a page built with a page builder app.

> **Quick summary**
>
> - You can send B2B customers to a dedicated page when they sign in, such as a B2B collection, a custom page or a page made with a page builder app.
> - Build the page in Shopify, then tell SparkLayer where to send customers: in the SparkLayer Core Script, or with the **B2B Account Redirect** extension if you use new customer accounts.
> - Designing the page is a Shopify change. We can't help with Shopify design or layout, so if you're unsure, work with a Shopify expert.

## How it works

When a signed-in B2B customer opens your store's account area (for example `/account`), SparkLayer normally sends them to the SparkLayer My Account interface. You can send them to a page of your choice instead: a central hub for your B2B store that highlights products, shares important information or links to account tools.

Setting up a B2B landing page:

1. **Choose a page**: A B2B collection, a custom page or a page builder page
2. **Build it in Shopify**: Add the products and content B2B customers should see first
3. **Set the redirect**: Tell SparkLayer to send signed-in B2B customers to its URL

## Choose a landing page

Start by choosing what kind of page to send customers to:

| Option | Example URL | Best for |
| --- | --- | --- |
| **A B2B product collection** | `/collections/b2b-products` | Customers who want to browse and order from your wholesale catalogue straight away |
| **A custom Shopify page** | `/pages/b2b-landing-page` | A welcome page with messaging, featured products, banners and links to account tools |
| **A page builder app** | `/pages/b2b-customer-landing-page` | A highly designed, branded B2B homepage or dashboard, without writing code |

### A B2B product collection

Create a collection in Shopify that holds the products you want B2B customers to see first. Manage collections in your Shopify admin at **Products > Collections** ([open in the Shopify admin](https://admin.shopify.com/collections?selectedView=all)).

### A custom Shopify page

Create a standard Shopify page, for example called "B2B Landing Page", at **Online Store > Pages** ([open in the Shopify admin](https://admin.shopify.com/pages)). You can also edit it at **Online Store > Customize** on your live theme. It could include:

- Welcome text or messaging
- Links to featured products or categories
- Helpful content or banners
- Links to account tools, such as invoices or quick order

What you can add depends on your theme, so you may need to ask your theme developer how best to approach it.

### A page builder app

Shopify page builder apps give you a drag-and-drop editor for designing pages. Options in the Shopify App Store include [PageFly](https://apps.shopify.com/pagefly?st_source=autocomplete\&surface_detail=autocomplete_apps), [Shogun](https://apps.shopify.com/shogun?st_source=autocomplete\&surface_detail=autocomplete_apps), [Instant](https://apps.shopify.com/instant-builder?st_source=autocomplete\&surface_detail=autocomplete_apps) and [many others](https://apps.shopify.com/categories/store-design-storefronts-page-builder/). Like other Shopify pages, each page you build has its own URL.

### Other ideas

You could also add:

- Quick links to quotes, past orders or special offers.
- B2B-only content using Shopify Liquid (see [Shopify B2B-only content](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-only-content.md)).
- A video or help resources for new customers.

## Send B2B customers to your landing page

Once your page is ready, tell SparkLayer to send B2B customers there. Use the Core Script, or the **B2B Account Redirect** extension if you use new customer accounts.

### With the SparkLayer Core Script (for your developer)

This option is a code change, so pass it to your developer. If you use new customer accounts, the [no-code option below](#with-new-customer-accounts) does the same job. Add this to your [SparkLayer Core Script](https://docs.sparklayer.io/developers/frontend.md), and change `goTo` to your landing page's URL:

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

### With new customer accounts

If you use Shopify's new customer accounts, you can set the destination in your Shopify admin instead:

1. Go to **Settings > Checkout** ([open in the Shopify admin](https://admin.shopify.com/settings/checkout)).
2. Under **Configurations**, click **Customize** beside your live configuration.
3. From the page selector at the top, open the **Orders** page.
4. Click **Apps** on the left, then turn on the **B2B Account Redirect** extension.
5. Optionally, enter a **Redirect Notice (Optional)** to show customers before they're redirected.
6. Enter your landing page in **Redirect Path (Optional)**, for example `/collections/b2b-products`. If you leave it blank, customers go to your homepage.
7. Click **Save**.

### Send customer groups to different pages

With Legacy customer accounts, you can send each customer group to a different page: for example, customers tagged `b2b-group-1` to `/collections/wholesale-page` and customers tagged `b2b-group-2` to `/collections/another-wholesale-page`.

In your SparkLayer Core Script, replace the `accountRedirect` code above with this Liquid code, and change the tags and URLs to suit your groups:

```javascript title="Core Script"
accountRedirect: {
  urlRegex: /\/account/g,

  {% assign goTo = "/index" %}
  {% for tag in customer.tags %}
    {% if tag == "b2b-group-1" %}
      {% assign goTo = "/collections/wholesale-page" %}
    {% elsif tag == "b2b-group-2" %}
      {% assign goTo = "/collections/another-wholesale-page" %}
    {% endif %}
  {% endfor %}

  goTo: {{ goTo | json }},
},
```

## Show B2B content on your landing page

You can use Shopify's Liquid templates to change what the landing page shows, depending on whether the customer is a B2B customer. For example:

```html
{% if customer.tags contains 'b2b' %}
  <p>Welcome back, valued wholesale customer!</p>
  <a href="/collections/b2b-products" class="button">Browse B2B Products</a>
{% else %}
  <p>This page is for B2B customers only.</p>
{% endif %}
```

For more examples, see [Shopify B2B-only content](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-only-content.md).


---

# Shopify payment methods

URL: https://docs.sparklayer.io/help/platforms/shopify/customisations/payment-methods
Applies to: Shopify

Manage B2B payments on Shopify: review Pay on Account and Pay by Invoice orders as draft orders, send Shopify invoices, and hide checkout payment methods.

> **Quick summary**
>
> - B2B customers on Shopify can pay upfront by card through the Shopify checkout, or use offline methods such as Pay by Invoice and Pay on Account.
> - Offline orders arrive in Shopify as **draft orders**, so you can review and edit them before sending an invoice or completing them.
> - You choose which payment methods each [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md) can use. To hide some Shopify checkout methods from B2B customers, use a Shopify app.

## How it works

Offline payment methods, such as **Pay by Invoice** and **Pay on Account**, let you review an order before you process it. Once you turn one on for a customer group, its customers see it in the **Payment Method** step of the SparkLayer checkout, next to options such as **Pay Online by Card**. When they choose it, they see a confirmation such as "We'll be in touch after you place your order to arrange payment details."

An order with an offline payment method:

1. **Customer chooses an offline method**: For example Pay by Invoice or Pay on Account
2. **Draft order created**: The order arrives in Shopify as a draft order
3. **You review it**: Check and edit the order, then send an invoice
4. **Customer pays**: The order is marked as paid and appears in Shopify Orders

When a customer chooses **Pay Online by Card**, they go to the Shopify checkout instead and pay there. The order arrives as a completed order. For every option, see the [payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md) guide, or follow each method step by step in the interactive guide [How payments work](https://docs.sparklayer.io/help/guides/how-payments-work.md).

## Review a draft order

Orders placed with an offline method, and orders placed as a quote, arrive in Shopify as draft orders by default. Review each one before you send an invoice.

1. In your Shopify admin, go to **Orders > Drafts** ([open in the Shopify admin](https://admin.shopify.com/draft_orders)) and open the order.
2. Check the products, quantities and prices. The customer's details are on the right.
3. Edit the order if you need to, as you would any Shopify draft order.

## Send an invoice from a draft order

When the order looks right, send the customer a Shopify invoice so they can pay online.

1. Open the draft order in your Shopify admin.
2. Under the order totals, click **Send invoice**. Shopify emails the customer, who can review the order and pay online.

When the customer pays, the order is marked as paid and appears in your Shopify **Orders**.

To change the email, go to **Settings > Notifications** ([open in the Shopify admin](https://admin.shopify.com/settings/notifications)) in your Shopify admin and open the **Draft order invoice** template.

For other ways to manage invoicing, see [Credit limits and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md).

## Hide payment methods in the checkout

When B2B customers choose **Pay Online by Card**, they go to the Shopify checkout. There they see every payment method you've set up in Shopify, such as credit card, PayPal or cash on delivery. See Shopify's guide to [payment methods](https://help.shopify.com/en/manual/payments/additional-payment-methods).

To show B2B customers only some of these, use a Shopify app that can hide payment methods conditionally:

1. In the Shopify App Store, search for apps that hide payment methods, such as [ETP Hide and Sort Payment Methods](https://apps.shopify.com/etp-hide-sort-payments?).
2. In the app, add a rule that applies when the customer has the tag `b2b`.
3. Choose the payment methods to hide for those customers, for example PayPal and Cash on Delivery (COD).

You can only hide the **Credit card** method if your store is on Shopify Plus, because of limits in Shopify's Payment Customization API.


---

# Email notifications

URL: https://docs.sparklayer.io/help/platforms/shopify/customisations/email-notifications
Applies to: Shopify

Customise Shopify emails for B2B customers: show B2B-only content and order details, hide discount pricing, rename payment methods and edit invites.

> **Quick summary**
>
> - B2B orders use your normal Shopify email notifications. You edit them in your Shopify admin at **Settings > Notifications** ([open in the Shopify admin](https://admin.shopify.com/settings/notifications)).
> - With small Liquid code changes, you can show content only to customers tagged `b2b`, include order details SparkLayer adds, hide discount pricing and rename payment methods.
> - The account invite email can only be customised if you use Legacy customer accounts.
> - These are code changes to Shopify templates: we can explain the approach, but we can't make the changes for you. We recommend working with a Shopify expert.## How it worksSparkLayer orders are Shopify orders (or draft orders), so customers get Shopify's standard notification emails. Each template is Liquid code you can edit in your Shopify admin. SparkLayer adds the `b2b` tag to B2B customers and some extra details to their orders. Your templates can use these to show different content to B2B customers.To edit a template:1) In your Shopify admin, go to **Settings > Notifications** ([open in the Shopify admin](https://admin.shopify.com/settings/notifications)).
2) Open the template you want to change, for example **Order confirmation**, and edit its code.
3) Test your change by triggering the email (for example, by placing a real order). Test with one customer tagged `b2b` and one without.## Show B2B-specific content in an emailTo show one message to B2B customers and another to everyone else, add this code to a template and change the content as you need:```html

  {% for tag in customer.tags %}
    {% if tag == 'b2b' %}

  	Content to show to B2B

    {% else %}

      Content to show to DTC

    {% endif %}
  {% endfor %}
```## Show order details from Additional detailsSparkLayer orders can carry extra data as order note attributes, which appear under **Additional details** on the order in Shopify. You can show these in emails, such as a delivery date or the payment method. For example, an order might have a `shipping-date` from a [custom checkout field](https://docs.sparklayer.io/help/ordering/checkout-fields.md) and a `sparkPaymentType` of `paymentOnAccount`.Add the code to these templates:* [Order confirmation](https://admin.shopify.com/email_templates/order_confirmation/preview)
* [Order invoice](https://admin.shopify.com/email_templates/order_invoice/preview)
* [Draft order invoice](https://admin.shopify.com/email_templates/draft_order_invoice/preview)```html
<p>Name of field: {{ attributes.Name of Field }}</p>
<p>Name of field: {{ attributes.Another Name of Field }}</p>
```For example, to show the shipping date and the payment method:```html
{{ attributes.shipping-date }}
{{ attributes.sparkPaymentType }}
```Put the code where it fits in your email layout, and adjust it to match your formatting.To show the order note:```html
{% if note != '' %} 
Note: {{ note }}
{% endif %}
```## Hide discount pricingBy default, a line item in the email can show the original price struck through, the discount amount and the final price. To show B2B customers only the final price, add this CSS before the closing `</head>` tag in each of these templates:* [Order confirmation](https://admin.shopify.com/email_templates/order_confirmation/preview)
* [Order invoice](https://admin.shopify.com/email_templates/order_invoice/preview)
* [Draft order invoice](https://admin.shopify.com/email_templates/draft_order_invoice/preview)```css
{% for tag in customer.tags %}
    {% if tag == 'b2b' %}
    <style>
        .order-list__item-original-price,
        .order-list__item-discount-allocation,
        p.total-discount {
          display: none;
        }
    </style>
    {% else %}

    {% endif %}
  {% endfor %}
```## Rename the payment methodThe order confirmation email shows a payment method at the bottom. To change what it says for B2B payment types, add this to the **Order confirmation** template:```html
{% assign sparkPaymentType = attributes.sparkPaymentType %}
{% if sparkPaymentType == 'paymentByInvoice' %}
 Invoice Payment [change this to the required payment name]
{% endif %}
```## Customise the account invite emailWhen you invite a buyer from SparkLayer Wholesale with **Invite a buyer**, Shopify sends them its **Customer account invite** email, and they sign in with a one-time code. The **Edit the email in Shopify** link in the invite window opens that template, under **Settings > Notifications > Customer notifications** ([open in the Shopify admin](https://admin.shopify.com/settings/notifications/customer)). See [Invite a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md). When you add customers in Shopify yourself, what you can customise depends on the version of [customer accounts](https://admin.shopify.com/settings/customer_accounts) your store uses.**New customer accounts.** Send customers to your store's login page (for example `yourstore.com/account`), where they enter their email and get a 6-digit access code. You can't customise that email.**Legacy customer accounts.** When you create a new customer, send them an account invite:1) In your Shopify admin, open the customer.
2) Click **More actions**, then **Send account invite**.The customer gets an email with an **Activate your account** button, so they can set a password. See Shopify's guide to [inviting customers to create accounts](https://help.shopify.com/en/manual/customers/customer-accounts#invite-customers-to-create-accounts).To change the invite email:1) In your Shopify admin, go to **Settings > Notifications > Customer notifications** ([open in the Shopify admin](https://admin.shopify.com/settings/notifications/customer)).
2) Under **Accounts and outreach**, open **Customer account invite** and edit the [account activation email](https://admin.shopify.com/email_templates/customer_account_activate/preview).You can make its content B2B-specific with the code in [Show B2B-specific content in an email](#show-b2b-specific-content-in-an-email). The same section has the other account emails, such as **Customer account welcome** and **Customer account password reset**.## Next steps- [B2B-only content](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-only-content.md): Show content on your store only to customers tagged b2b
- [Shopify payment methods](https://docs.sparklayer.io/help/platforms/shopify/customisations/payment-methods.md): Review Pay on Account and Pay by Invoice orders and send Shopify invoices
- [Checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md): Collect extra details at checkout, such as a PO number or delivery date


---

# Shopify Flow for B2B

URL: https://docs.sparklayer.io/help/platforms/shopify/customisations/flow
Applies to: Shopify

Import ready-made Shopify Flow workflows for SparkLayer to mark B2B orders as paid, tag orders and customers, keep RRP metafields in sync and email your team.

> **Quick summary**
>
> - [Shopify Flow](https://help.shopify.com/en/manual/shopify-flow) automates tasks in your store when something happens, such as an order being created.
> - We've made ready-made B2B workflows for orders, customers, products and emails. Download one and [import it](https://help.shopify.com/en/manual/shopify-flow/manage/manage#import-a-workflow) into Shopify Flow.
> - Shopify Flow is a free app, available on every Shopify plan.

## How it works

A Shopify Flow workflow has a trigger, an optional condition and one or more actions. Many B2B workflows use the `b2b` tag SparkLayer adds to customers and orders, so they act only on B2B orders. For example, a workflow that tags B2B orders works like this:

Example workflow: tag orders as B2B:

1. **Start when**: Order created
2. **If**: Any of the order customer's tags match `b2b`
3. **Then**: Add the order tag `b2b_order`

To use one of our workflows:

1. Download the `.flow` file from the tables below.
2. In Shopify Flow, [import the workflow](https://help.shopify.com/en/manual/shopify-flow/manage/manage#import-a-workflow).
3. Check its settings, such as tags or email addresses, and change them to suit your store.
4. Turn the workflow on and save it.

## Order workflows

These workflows handle B2B orders after they're placed.

| Workflow | What it does | Download |
| --- | --- | --- |
| **Mark order as paid** | Marks an order as paid automatically when a B2B customer orders with a manual payment method. | [Download](https://cdn.shopify.com/s/files/1/0565/7500/0728/files/Mark_B2B_orders_as_paid_0a29877b-9fb6-4d8a-9f10-ca27ba055b66.flow?v=1635839553) |
| **Mark Payment on Account order as paid** | Marks an order as paid automatically when a B2B customer orders with **Payment on Account**. | [Download](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/Mark_B2B__Payment_on_Account__orders_as_paid.flow?v=1710337044) |
| **Archive B2B orders** | Archives B2B orders automatically, to keep them out of your main Shopify orders view alongside retail orders. | [Download](https://cdn.shopify.com/s/files/1/0565/7500/0728/files/Archive_B2B_Orders.flow?v=1635838493) |
| **Tag pre-orders** | Tags an order when it includes pre-order products. | See [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md) |
| **Tag order with the customer's net terms** | Tags each order with the [net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) set on the customer (in a metafield). | [Download](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/Tag_order_with_what_net_terms_the_customer_is_on.flow?v=1722499862) |
| **Populate order metafield from custom checkout fields** | Copies data from [custom checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md) (such as a date selector) on the draft order into metafields on the completed order. | [Download](https://cdn.shopify.com/s/files/1/0631/8453/5705/files/Update_order_Metafield_with_SparkLayer_Custom_Attributes_1.flow?v=1754639426) |
| **Control B2B order fulfilment** | Sends orders from your wholesale customer group to a particular Shopify stock location for fulfilment, so B2B orders are handled separately from retail. | [Download](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/B2B_Fulfilment_location_11.flow?v=1760365759) |

## Customer workflows

These workflows update a customer's tags as they order and spend.

| Workflow | What it does | Download |
| --- | --- | --- |
| **Switch tag on first order** | When a B2B customer places their first order, replaces their tag with a new one and sends an internal email. | [Download](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/B2B_-_switch_tag_assigned_to_a_B2B_customer_after_their_first_order_acb41199-9408-48f9-8e5e-f1228e836ceb.flow?v=1714641440) |
| **Adjust customer group tag by spend** | If you have customer groups such as Gold, Silver and Bronze, updates the customer's tag based on how much they spend, which moves them to a different B2B group. | [Download](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/Automatically_adjust_customer_tag_for_customer_group_depending_on_spend.flow?v=1722499466) |

## Product workflows

These workflows keep product data and sales channels up to date.

| Workflow | What it does | Download |
| --- | --- | --- |
| **Remove restock date when a variant is back in stock** | If you use [pre-orders](https://docs.sparklayer.io/help/storefront/stock-display.md) with a restock date, removes the date from the metafield when the product is back in stock. | [Download](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/Remove_restock_date_in_metafield_when_variant_back_in_stock.flow?v=1722499600) |
| **Add new products to the SparkLayer Wholesale and Online Store sales channels** | Makes new products available in the **SparkLayer Wholesale** and **Online Store** sales channels automatically. | [Download](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/Automatically_mark_new_products_with_B2B_ordering_Online_store_sales_channels.flow?v=1722499725) |
| **Add RRP metafield when product status changes** | When a product's status changes, writes each variant's Shopify price into its RRP field, in US dollars. Change `usd` in its value to your currency before you turn it on. | [Download](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/Add_RRP_when_product_status_updated.flow?v=1772815525) |
| **Update RRP metafield when a product is updated** | Once an hour, copies the Shopify price of each changed variant into its RRP field. Before you turn it on, change its currency and timing: see [Show RRPs to your trade customers](https://docs.sparklayer.io/help/guides/show-rrp.md#set-your-currency-and-timing). | [Download](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/Update_RRP_Metafield_when_product_updated.flow?v=1772815525) |

## Email workflows

These workflows email you, your team or your sales agents.

| Workflow | What it does | Download |
| --- | --- | --- |
| **Send an email with order details** | Emails an address you choose when a B2B customer places an order with a particular B2B payment status. Useful for notifying the team who handle B2B accounts (see the example below). | [Download](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/B2B_-_Draft_order-_Send_email_to_verify_the_order.flow?v=1762519098) |
| **Send notification based on custom checkout fields (draft orders)** | Triggers an action, such as an internal email, based on [custom checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md). | [Download](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/B2B_-_Draft_Checkout_Custom_Attributes_-_Send_email_based_on_criteria.flow?v=1717486893) |
| **Send notification based on custom checkout fields (completed orders)** | Triggers an action, such as an internal email, based on [custom checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md). | [Download](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/B2B_-_Completed_Order_Checkout_Custom_Attributes_-_Send_email_based_on_criteria.flow?v=1717486893) |
| **Email sales agent when order placed by customer** | Notifies [sales agents](https://docs.sparklayer.io/help/sales-ordering.md) when a customer places an order, based on rules you set. | [Download](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/Sales_Agents_-_Email_sales_agent_when_order_placed_by_customer.flow?v=1726494991) |

### Change the email content

You can add order and customer details to a workflow's email with variables. In the **Send an email with order details** workflow, the **Send internal email** action has an **Email address**, a **Subject** and a **Message**. For example:

- **Subject**: Action required - Draft Order to review
- **Message**:

```liquid
**New Draft Order Created**

**Date:** {{ draftOrder.createdAt }}

**Customer:** {{ draftOrder.customer.displayName }}

**Email:** {{ draftOrder.customer.email }}

**Total:** {{ draftOrder.totalPriceSet.shopMoney.amount }} {{ draftOrder.totalPriceSet.shopMoney.currencyCode }}

**Items Ordered:**
{% for lineItem in draftOrder.lineItems %}
- {{ lineItem.quantity }} × {{ lineItem.title }} – {{ lineItem.originalUnitPriceSet.shopMoney.amount }} {{ lineItem.originalUnitPriceSet.shopMoney.currencyCode }}
{% endfor %}

=====
Please review this customer's order within **Shopify > Orders > Drafts**.
```

Click **Add variable** to insert other details.


---

# Reporting and filtering

URL: https://docs.sparklayer.io/help/platforms/shopify/customisations/reporting-and-filtering
Applies to: Shopify

Report on SparkLayer B2B sales in Shopify by filtering on the SparkLayer Wholesale sales channel, the b2b order tag and the sparkPaymentType order attribute.

> **Quick summary**
>
> - SparkLayer is a Shopify sales channel, **SparkLayer Wholesale**, so you can filter most of your Shopify admin to show only SparkLayer orders.
> - Every SparkLayer order also has the tag `b2b`, and order note attributes such as `sparkPaymentType`, which you can use for reports, filters and automations.

## Filter by sales channel

SparkLayer works as a [sales channel](https://help.shopify.com/en/manual/online-sales-channels) in Shopify, and you can filter most areas of the Shopify admin by sales channel.

1. In your Shopify admin, open the area you want to filter, such as your orders or a report, and open its filters.
2. Add the filter **Sales channel name** **is** **SparkLayer Wholesale**.
3. Click **Apply filters**.

For a quick view without filters, **Orders** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/activity)), or **SparkLayer Wholesale > Orders** in the Shopify app shows your B2B orders and sales over time, and its **View in Shopify** button opens your Shopify orders filtered to B2B.

## Filter by order tag and attributes

SparkLayer also adds a tag and extra data to every order placed by a B2B customer. Use them in Shopify reports, filters and automations.

| Attribute | What it contains |
| --- | --- |
| `tag` | The tag `b2b`, added to every order placed through SparkLayer. Useful for filtering and segmenting orders, and for automations such as [Shopify Flow](https://docs.sparklayer.io/help/platforms/shopify/customisations/flow.md). |
| `note` | Order note attribute `sparkCartId`. Mainly for our internal debugging. |
| `note` | Order note attribute `sparkPaymentType`: the payment option used. One of `upfrontPayment`, `paymentOnAccount`, `paymentByInvoice` or `quote`. |

On an order in Shopify, the tag appears in the **Tags** card and the note attributes under **Additional details**. For the full mapping of order data, see [Shopify metafields and data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#order-data).


---

# Wix

URL: https://docs.sparklayer.io/help/platforms/wix
Applies to: Wix

Add B2B and wholesale ordering to your Wix store with the SparkLayer app: what works on Wix, how setup works, its limitations and the demo store.

> **Quick summary**
>
> - The SparkLayer app adds B2B pricing, a B2B cart and an account area to your existing Wix store. Retail (DTC) shoppers see your store as it is today.
> - It works with Wix Editor and Wix Studio, on the Starter to Enterprise SparkLayer plans. Wix stores start with a 14-day free trial.
> - A customer becomes a B2B customer when their Wix contact has the `b2b` label and is a site member.
> - Product card pricing, metafields and Wix discounts aren't available on Wix: see [Wix limitations](https://docs.sparklayer.io/help/platforms/wix/limitations.md).

## How SparkLayer works on Wix

You install the [SparkLayer for Wix app](https://www.wix.com/app-market/web-solution/sparklayer-b2b-wholesale) from the Wix App Market. SparkLayer then syncs your products and B2B customers from Wix.

SparkLayer adds its widgets to your product pages automatically, so there's no code to add. You keep your Wix design, and can run retail and B2B from the same store.

You manage B2B prices and ordering rules in the [SparkLayer Dashboard](https://docs.sparklayer.io/help/dashboard.md). Products, customers and orders stay in Wix.

## Install at a glance

Setting up SparkLayer on Wix:

1. **Install the app**: From the Wix App Market
2. **Create your account**: Register with SparkLayer and start your trial in Wix
3. **Label customers**: Give B2B contacts the `b2b` label and make them site members
4. **Set prices and rules**: Price lists and customer groups in the SparkLayer Dashboard
5. **Test and launch**: Sign in as a B2B customer and place a test order

The full steps are in [Install SparkLayer on Wix](https://docs.sparklayer.io/help/platforms/wix/install.md). You don't need a developer. Our team can also set it up with you: [book an onboarding call](https://connect.sparklayer.io/onboarding-meeting).

## What's specific to Wix

| Topic | On Wix |
| --- | --- |
| **Installing** | An app from the [Wix App Market](https://www.wix.com/app-market/web-solution/sparklayer-b2b-wholesale). |
| **B2B customers** | Wix contacts with the `b2b` label who are site members. |
| **Customer groups** | Add the group's label to the contact as well as `b2b`, for example `b2b` and `b2b-vip`. |
| **Widgets** | Added to your product pages automatically when you install the app. |
| **Orders** | Created in Wix under **Sales > Orders**, with the tag `b2b`. |
| **Billing** | Through your Wix account. |
| **Metafields** | Not supported by Wix, so settings that rely on them, such as pack sizes and RRP pricing, aren't available. |

## Limitations

The main differences from other platforms:

- Product cards on gallery and collection pages don't show B2B prices, and metafields (such as pack sizes) aren't available.
- Wix stores accept one currency, so orders are created in your store's default currency.
- Wix discounts can't be used with SparkLayer. Use SparkLayer's own [discounts](https://docs.sparklayer.io/help/pricing/discounts.md) instead.

See [Wix limitations](https://docs.sparklayer.io/help/platforms/wix/limitations.md) for the full list, and [Compare platforms](https://docs.sparklayer.io/help/platforms/compare.md) to check a feature across platforms.

## Try the Wix demo store

See SparkLayer on a working Wix store at [demo.wix.sparklayer.io](https://demo.wix.sparklayer.io/). To sign in as a B2B customer, click **Try Demo** in the main navigation.

## Wix guides

- [Install SparkLayer on Wix](https://docs.sparklayer.io/help/platforms/wix/install.md): Install the app, label your customers and add your B2B prices
- [Wix FAQs](https://docs.sparklayer.io/help/platforms/wix/faqs.md): Plans, products, payments and orders on Wix
- [Limitations](https://docs.sparklayer.io/help/platforms/wix/limitations.md): What works differently, or isn't supported, on Wix
- [Error codes](https://docs.sparklayer.io/help/platforms/wix/error-codes.md): What an error in the cart means and how to fix it
- [Metafields](https://docs.sparklayer.io/help/platforms/wix/metafields.md): Why metafield settings aren't available on Wix
- [Cancel or uninstall](https://docs.sparklayer.io/help/platforms/wix/uninstall.md): Cancel SparkLayer, see what happens to your data or start again on a new store


---

# Install SparkLayer on Wix

URL: https://docs.sparklayer.io/help/platforms/wix/install
Applies to: Wix

Install SparkLayer on Wix: allow site members and add SKUs, install the app, label B2B contacts, style the widgets, then set up prices and test an order.

> **Quick summary**
>
> - Install the SparkLayer app from the Wix App Market and create your SparkLayer account. SparkLayer connects to your store automatically, and our team completes the storefront install once you [invite us as a collaborator](#invite-our-team-as-a-collaborator), so there's no code to add.
> - A customer becomes a B2B customer when their Wix contact has the `b2b` label and is a site member.
> - You manage SparkLayer in the SparkLayer Dashboard at app.sparklayer.io, or in the SparkLayer app in your Wix dashboard: they have the same screens. 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.
> - It works with Wix Editor and Wix Studio. Our team can set it up with you: [book an onboarding call](https://connect.sparklayer.io/onboarding-meeting).

Setting up SparkLayer on Wix:

1. **Before you start**: Site members, SKUs, payments and shipping in Wix
2. **Install**: Add the app and create your SparkLayer account
3. **Connect**: Label B2B contacts so they sync
4. **Widgets**: Added for you; match them to your brand
5. **Next steps**: Prices, customer groups, 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.

> **What happens after you install**
>
> You don't need a developer. Once you've installed the app, [invite our team as a collaborator](#invite-our-team-as-a-collaborator) and we complete the storefront install for you: B2B pricing and the buy widget on product pages, the B2B My Account area and the B2B cart. You do the rest in your Wix dashboard and the SparkLayer Dashboard. Two optional extras use code: CSS to match your brand, which you can copy from our example, and [JavaScript options](#javascript-options), which are marked "for your developer".

## Before you start

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

- **Site members allowed.** B2B customers sign in as site members. Go to **Settings > Site Member Settings > Signup & Login Security** and, under **Who can be a site member**, choose **Everyone who signs up**.
- **A unique SKU on every product** you sell to B2B customers. SparkLayer stores B2B prices by SKU, so a product without one can't be bought. See [Add SKUs to your products](#add-skus-to-your-products).
- **A payment method** set up in **Settings > Accept Payments**.
- **Shipping rules** set up in **Settings > Shipping and Delivery**, so orders can be placed. 

Once SparkLayer is running, you'll mostly use three areas of Wix: **Catalog > Store Products > Products** for products and SKUs, **Customers & Leads > Contacts** for B2B customers, and **Sales > Orders** for B2B orders.

### Add SKUs to your products

1. In Wix, go to **Catalog > Store Products > Products** and open a product. The product list has a **SKU** column, so you can spot products without one.
2. For a product without variants, enter a **SKU** in the **Inventory and shipping** section.
3. For a product with variants (such as colour or size), turn on **Manage pricing and inventory for each product variant**. Then edit the variants in the **Product variants** section, enter a different **SKU** for each variant and click **Apply**.
4. Save the product.

To add SKUs to many products at once, use Wix's product import or bulk edit.

## Install SparkLayer

Add the app from the Wix App Market, then create your SparkLayer account.

1. Open the [SparkLayer for Wix app](https://www.wix.com/app-market/web-solution/sparklayer-b2b-wholesale) in the Wix App Market. Or, in Wix, go to **Apps > App Market** and search for **SparkLayer**.
2. Add the app and choose the Wix site to install it on.
3. Create your SparkLayer account: enter your **Email Address**, **Full Name**, **Company Name**, **Company Website** and a **Password**, then click **Create Account**. If you already have an account, sign in instead.
4. Keep a note of the email address and password. You'll use them to sign in to the [SparkLayer Dashboard](https://app.sparklayer.io/).
5. Confirm the SparkLayer billing plan in Wix to start your free trial. Billing for SparkLayer runs through your Wix account.

## Connect your store

SparkLayer connects to your Wix store as soon as you install the app. It then syncs your products, and every contact with the `b2b` label, from Wix. To finish connecting, mark your B2B customers.

To see your progress, open the app in Wix at **Apps > Manage Apps** (it's listed as **SparkLayer B2B & Wholesale**). It shows **Your Wix store is connected to SparkLayer**, the setup tasks still to do, and a **Go To Dashboard** button.

In the SparkLayer Dashboard, click **Open Setup** on **Home** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale** in the Shopify app to see the steps still to do. **Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app shows **Wix** as **Your platform**.

If the SparkLayer Dashboard shows **We need you to confirm your SparkLayer plan**, you can carry on setting up. 

### Mark customers as B2B

SparkLayer only syncs Wix contacts with the `b2b` label. Each customer must also be a site member, so they can sign in.

1. In Wix, go to **Customers & Leads > Contacts**. Click **Create New** to add a contact, or open an existing one.
2. Make sure the contact has a name, email address and a complete address, with every address field filled in. Keep a note of the email address: the customer signs in with it.
3. Under **Labels**, click **Add Label**, type `b2b` and click **Add**.
4. For a customer in a customer group other than the base customer group, add that group's label too. Use the group's label exactly as shown on the group's page at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app. For example, a VIP customer has the labels `b2b` and `b2b-vip`.
5. Under **Member info**, click **Set Contact as Member**. Wix emails the customer a **Create New Password** link, and their member status changes to **Site Member**. Customers can also use **Forgot password?** on your store's sign-in page.

Once you've created a label in Wix, don't edit it. See [Wix limitations](https://docs.sparklayer.io/help/platforms/wix/limitations.md) for how Wix handles a renamed `b2b` label.

> **Addresses sync once**
>
> When a contact is labelled `b2b` for the first time, SparkLayer copies their address once. If a required field (such as name, address line or postcode) is missing, the address isn't synced at all, and no sync error is logged. After that, address changes in Wix don't sync to SparkLayer, and changes in the customer's SparkLayer address book don't sync to Wix.

### 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.
3. If they're listed, they've synced. Click **View** to check their details: under **Identifiers**, the **Platform ID** is their Wix contact ID, the one at the end of the contact's page URL in Wix, after `/contacts/view/`.

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

On Wix, our team completes the storefront install for you: B2B pricing and the buy widget on product pages, the B2B [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) area and the B2B [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md). There's no code for you to add. When a B2B customer signs in, product pages show their B2B prices and a way to order. See [Storefront widgets](https://docs.sparklayer.io/help/storefront/interfaces.md) for what each widget does.

If prices disappear when a B2B customer signs in, the storefront install probably isn't complete. Check you've invited our team, or [contact us](https://docs.sparklayer.io/help/support.md).

### Invite our team as a collaborator

To let us complete the install, invite us to your Wix site:

1. In Wix, go to **Settings > Roles & Permissions** and click **Invite collaborators**.
2. Enter our support address, [support@sparklayer.io](mailto:support@sparklayer.io). 
3. Give us these roles: **Website Manager**, **CMS Editor**, **Marketing Manager** and **Customer Relations Manager**.
4. Send the invite, then let us know through [support](https://docs.sparklayer.io/help/support.md).

If the invite doesn't reach us, create an invite link in the same place and send it to us instead.

### Match the widgets to your brand (optional)

The widgets work as they are, with generic fonts and colours. To use your own colours and fonts, add a short piece of CSS (style code) to your site. Copy the example below and change the colours and font names, or ask your developer. Our [support team](https://docs.sparklayer.io/help/support.md) can also help.

How you add the CSS depends on your editor. For the full list of variables, see [Customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md).

**Wix Editor:**

1. In your Wix dashboard, go to **Settings > Custom Code** and click **Add Custom Code**.
2. Paste the CSS into **Paste the code snippet here** and give it a **Name**.
3. Under **Add Code to Pages**, choose **All pages** and **Load code on each new page**.
4. Save the code. It's listed under **Head** with **Applied on: All pages**, and you can edit it at any time.

**Example CSS for Wix Editor**

```html
<style>
:root {
  /* Set the brand styling */
  --b2b-brand-color: #5b36f5; /* Main brand colour */
  --b2b-brand-color-hover: #82ACFF; /* Main brand colour hover */
  --b2b-brand-font: Roboto, sans-serif; /* Main brand font */
  --b2b-brand-font-heading: Roboto, sans-serif; /* Main brand heading font */

  /* Update colours */
  --spark-default-body-color: #555555; /* Main body colour */
  --spark-primary-color: #000000; /* Main title colour */
  --spark-secondary-color: var(--b2b-brand-color); /* Main highlight colour */
  --spark-link-color: var(--b2b-brand-color); /* Link colour */

  /* Typefaces */
  --spark-font-default: var(--b2b-brand-font); /* Body typeface */
  --spark-font-highlight: var(--b2b-brand-font-heading); /* Highlight typeface */
  --spark-font-weight-default: 400; /* Default font weight */
  --spark-font-weight-medium: 500; /* Medium font weight */
  --spark-font-weight-heavy: 600; /* Bold font weight */

  /* General */
  --spark-border-radius-default: 0; /* Default border radius */
  --spark-drawer-max-width: 700px; /* Width of overlay */
  --spark-drawer-max-width-wide: 1000px; /* Width of overlay in maximised view */

  /* Font sizes */
  --spark-font-default-size: 14px; /* Default font size */
  --spark-font-default-size-small: 14px; /* Default font size - small screens */
  --spark-header-font: var(--b2b-brand-font-heading); /* Header typeface */
  --spark-header-font-weight: 500; /* Header font weight */
  --spark-h1-fontsize: 24px; /* Header 1 font size */
  --spark-h2-fontsize: 22px; /* Header 2 font size */
  --spark-h3-fontsize: 20px; /* Header 3 font size */
  --spark-h4-fontsize: 16px; /* Header 4 font size */
  --spark-h5-fontsize: 15px; /* Header 5 font size */
  --spark-h6-fontsize: 14px; /* Header 6 font size */

  --spark-pricing-fontsize: 16px; /* Font size of pricing */
  --spark-pricing-font-weight: 500; /* Font weight of pricing */
  --spark-pricing-fontsize-small: 14px; /* Font size of pricing on mobile */

  --spark-product-code-fontsize: 16px; /* Font size of product code */
  --spark-product-code-font-weight: 500; /* Font weight of product code */
  --spark-product-code-fontsize-small: 14px; /* Font size of product code on mobile */
  --spark-product-stockstatus-align: flex-start; /* Alignment of stock status for single variants */

  /* Buttons */
  --spark-button-font-family: var(--b2b-brand-font-heading); /* Button typeface */
  --spark-button-color: var(--b2b-brand-color); /* Default sutton colour */
  --spark-button-color-highlight: var(--b2b-brand-color-hover); /* Default button colour hover */
  --spark-button-large-color: var(--b2b-brand-color); /* Large button colour */
  --spark-button-large-color-highlight: var(--b2b-brand-color-hover); /* Large button colour hover */
  --spark-border-radius-button: 0; /* Button border radius */
  --spark-button-font-weight: 600; /* Button font weight */
  --spark-button-text-transform: none; /* Button text transform */
  --spark-button-text-letter-spacing: 0; /* Button letter spacing */
  --spark-button-padding: 1em 2.75em; /* Button padding */
  --spark-button-small-font-size: 16px; /* Small button font size */

  /* Tables */
  --spark-table-border-color: #CCCCCC; /* Table border colour */
  --spark-table-header-background-color: #F1F1F1; /* Table header background */
  --spark-table-header-text-color: #222222; /* Table header font colour */
  --spark-table-header-font-weight: 500; /* Table header font weight */

  /* Product Card */
  --spark-product-card-button-radius: 0; /* Button radius */
  --spark-product-card-button-padding: 0.75em 1em; /* Button padding */
  --spark-product-card-pricing-font-size: 15px; /* Pricing font size */
  --spark-product-card-pricing-font-size-small: 14px; /* Pricing font size on mobile */
  --spark-product-card-select-min-height: 0; /* Set a min-height for select menu */
  }
</style>
```

**Wix Studio:**

1. In your Wix dashboard, go to **Site & Mobile App > Edit Site**.
2. In the editor, click **Code** in the left-hand menu.
3. In the **CSS** section, open `global.css` and add the CSS variables.

For example, to change the colours and fonts:

```html
<style>
:root {
  /* Set the brand styling */
  --b2b-brand-color: #5b36f5; /* Main brand colour*/
  --b2b-brand-color-hover: #82ACFF; /* Main brand colour hover */
  --b2b-brand-font: Roboto, sans-serif; /* Main brand font */
  --b2b-brand-font-heading: Poppins, sans-serif; /* Main brand heading font */
  }
 </style> 
```

## Next steps

Once your customers are syncing, 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**. Enter a **Name**, a **Handle** and the **Currency**, then save. You can't change the handle or currency later. See [Managing pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md).

   **More detail**

   For prices worked out from Wix, tick **Enable automatic pricing** and choose **Wix Default Price** as the **Pricing source**. Then tick **Apply a percentage variation** and set it, for example 50% **Decrease**. Depending on your Wix tax setup, SparkLayer can also allow for tax when it works out automatic prices.

   For exact prices, upload a CSV instead. This also lets you set quantity pricing.

   When you create the price list, you're asked whether to assign it to your default B2B customer group. You can change this later.

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. The base customer group, with the label `b2b`, applies to every B2B customer. At a minimum, assign it a price list; you can also choose its payment methods and order limits. To give some customers different rules, click **Create customer group** and add the new group's label to those contacts in Wix. You can manage a group's rules once at least one customer is in it. See [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md).

3. **Place a test order.** Sign in to your store as your test B2B customer and open a product that has a SKU. You should see your B2B prices. Add items, check out, and try each payment method you offer. The order appears in **Sales > Orders**. See [How B2B orders arrive in Wix](#how-b2b-orders-arrive-in-wix).

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. Open a contact in **Customers & Leads > Contacts** and send a message from the **Inbox** tab, or select several contacts and click **Send Email Campaign**. 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 Wix

Every order goes to **Sales > Orders** in Wix. Its payment 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 in Wix |
| --- | --- | --- |
| **Pay on Account** | Checks out without entering payment details. | **Unpaid**. Mark it as paid once you've received payment. |
| **Pay by Invoice** | Checks out without entering payment details. | **Unpaid**. Mark it as paid once you've received payment. |
| **Pay Online by Card** | Goes to the Wix checkout and pays straight away, with any payment method you've set up in Wix (such as card or PayPal). Sometimes called pro-forma payment. | **Paid**, ready to fulfil. |
| **Request for Quote** | Submits the order without choosing a payment method. | **Unpaid**. Mark it as paid once you've received payment. |

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**.

Every order placed through SparkLayer also gets the tag `b2b` in Wix. Use it to filter orders, segment them or trigger automations.

## More settings on Wix

### Pre-orders and pre-order limits

SparkLayer supports pre-orders (also called back orders) on Wix, so B2B customers can order products that aren't in stock yet. You turn them on for each product in Wix.

1. In Wix, open the product and turn on **Track inventory**.
2. Turn on **Pre-order**.
3. Optionally, enter a **Pre-order message**, such as "Back order", to tell customers when the product will ship.
4. Under **Pre-order limit**, choose **No limit**, or **Limit to** and enter a number, such as `50`. On a product with variants, the limit applies to each variant.

Keep **Track inventory** on. If pre-order is on without it, the product doesn't sync and shows "Wix product has pre-order enabled but stock is not tracked".

B2B customers then see a pre-order message on the product page and can buy the product. See [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md) for how SparkLayer shows stock.

Wix Payments only supports pre-orders that are delivered within 12 months of purchase and aren't part of a crowdfunding campaign.

### Tax

SparkLayer uses the tax rules you've set up in Wix. To choose how tax is charged at checkout, go to **Settings > Tax**. Under **How would you like to collect tax?**, choose **Tax should be added at checkout** or **Tax is already included in my prices**. See Wix's guide to [including tax in the product price](https://support.wix.com/en/article/including-tax-in-the-product-price).

### SparkLayer shipping

By default, B2B orders use your Wix shipping methods. To use SparkLayer's own [shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md) instead:

1. In Wix, go to **Settings > Shipping, Delivery & Fulfillment**. You need at least one shipping region, such as the UK or USA.
2. Click **Manage Your Apps** below the shipping region.
3. Turn on **Spark Layer Shipping** and click **Save**.
4. In the SparkLayer Dashboard, 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. See [Shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md).

### Sales agents

[Sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md) works on Wix, so your sales team can sign in and place orders for B2B customers. Sales agents need the Starter plan or above: Starter includes 1, Growth 2 and Pro 5.

1. Set the sales agent up as a Wix contact with a complete address and the `b2b` label, so they sync to SparkLayer.
2. In the SparkLayer Dashboard, go to **Sales Agents > Agents** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/v2/customers/agents)), or **SparkLayer Wholesale > Sales agents** in the Shopify app and click **Add sales agent**.
3. Choose the contact under **Customer**, then choose a **Role**:
   - **Sales agent**: can place orders and manage addresses, shopping lists and company access on behalf of customers.
   - **Sales administrator**: all sales agent permissions, plus editing order prices and creating new customers.
4. Click **Add agent**.

### 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 Wix, add them in **Settings > Custom Code**: click **Add Custom Code** and paste in the script. Each example below sets `window.sparkWixOptions`, so if you use more than one, combine their settings into one script.

`window.sparkWixOptions` accepts the same options as the Core Script's `window.sparkOptions`, where Wix supports them. Use the exact option names from [Core Script options](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md). For example:

| Option | What it does |
| --- | --- |
| `termsAndConditionsLink` | The link to your terms and conditions at checkout. |
| `checkoutCustomElements` | Extra fields at checkout, such as a delivery date. |
| `accountRedirect` | Where to send signed-in customers who open a matching page. |
| `display` | Display settings, such as `darkTheme`. |
| `translations` | Your own wording for SparkLayer's text, by language. See [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md). |
| `language` | The language SparkLayer uses. |
| `paymentMethodsOrder` | The order payment methods are shown in. |
| `cartRedirect` | Where to send signed-in customers, with the cart open. |

**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
<script>
  window.sparkWixOptions = {
  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',
        },
      },
    ],
  };
</script>
```

**Redirect customers after they sign in**

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

```javascript
<script>
  window.sparkWixOptions = {
   accountRedirect: {
      urlRegex: /\/account/g,
      goTo: "/index", // page to redirect logged in users to
   },
  };
</script>
```

**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
<script>
  window.sparkWixOptions = {
     display: {
         darkTheme: true,
      },
  };
</script>
```

## FAQs and troubleshooting

**Can you set up SparkLayer for me?**

Yes. [Book an onboarding call](https://connect.sparklayer.io/onboarding-meeting) and our team walks you through setup. We complete the storefront install for you once you [invite us as a collaborator](#invite-our-team-as-a-collaborator). See [Wix FAQs](https://docs.sparklayer.io/help/platforms/wix/faqs.md).

**Prices disappear when a B2B customer signs in**

The storefront install probably isn't complete. [Invite our team as a collaborator](#invite-our-team-as-a-collaborator) so we can finish it, or [contact us](https://docs.sparklayer.io/help/support.md) if you already have.

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

Check that the customer's Wix contact has the `b2b` label and is a site member, 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).

**A customer's address is missing in SparkLayer**

Addresses sync only once, when the `b2b` label is first added, and only if every required field is filled in. The customer can add the address in their [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) address book.

**The cart shows an error code**

See [Wix error codes](https://docs.sparklayer.io/help/platforms/wix/error-codes.md) for what it means and how to fix it.

**Where can I find more help?**

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


---

# Wix FAQs

URL: https://docs.sparklayer.io/help/platforms/wix/faqs
Applies to: Wix

Answers to common questions about SparkLayer on Wix: plans and billing, setup, themes, currencies, B2B-only products, stock and managing B2B orders.

## Plans and billing

**Which SparkLayer plans can I use on Wix?**

Every SparkLayer plan from Starter to Enterprise works with Wix. See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md) and the [SparkLayer pricing page](https://www.sparklayer.io/pricing/).

**How does billing work?**

Billing is managed through your Wix account and charged monthly, or annually if you choose that option.

## Wix setup

**Where do I find the SparkLayer Wix app?**

In the [Wix App Market](https://www.wix.com/app-market/search-result?query=sparklayer). See [Install SparkLayer on Wix](https://docs.sparklayer.io/help/platforms/wix/install.md).

**Which Wix plan do I need?**

SparkLayer works with Wix Editor and Wix Studio sites. You need an active Wix store.

**Can I run retail (DTC) and B2B on the same store?**

Yes. You can install SparkLayer on your existing retail Wix store and run both from it. We call this a hybrid setup. When B2B customers sign in, they see the SparkLayer [frontend interfaces](https://docs.sparklayer.io/help/storefront.md) with their prices and ordering options. Try it on our [B2B and retail demo store](https://demo.wix.sparklayer.io/).

## Store setup

**Can you install SparkLayer on my Wix store for me?**

Yes, free of charge. To ask our team, click **Request installation** at **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app in the SparkLayer Dashboard. We can usually do this within 1–2 working days. We then offer an onboarding session to walk you through how everything works. See [Request free installation](https://docs.sparklayer.io/help/support.md#request-free-installation).

**Does SparkLayer work with any Wix theme?**

Yes, SparkLayer works with all Wix themes. Once you've installed the app, our team completes the storefront install for you after you [invite us as a collaborator](https://docs.sparklayer.io/help/platforms/wix/install.md#invite-our-team-as-a-collaborator).

**How does SparkLayer affect my Wix theme?**

The SparkLayer widgets (B2B pricing, the cart and the My Account area) only load when a customer in a B2B customer group signs in. Everyone else sees your store as it is today, so you control exactly who sees B2B prices and can place B2B orders.

**I already use a wholesale or B2B app. Can I still use SparkLayer?**

Yes. SparkLayer can run alongside it, so you can try SparkLayer first and uninstall the other app when you're ready. If the other app changed your store's code, you can ask its developer to remove those changes, but you don't have to.

## Payments and currencies

**Can customers use my existing Wix payment methods?**

Yes, when they choose **Pay Online by Card** at the SparkLayer checkout. They're then taken to the Wix checkout, which shows every payment method you've set up in Wix (such as PayPal or Affirm). Any payment method Wix supports can be used this way.

**Can I use multiple currencies for B2B customers?**

Only partly. A Wix store [can only accept one currency](https://support.wix.com/en/article/wix-stores-request-selling-in-multiple-currencies), such as GBP. If you create price lists in other currencies 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:

- Signed-in B2B customers see prices in their price list's currency, at the exchange rate at that time.
- If they order in a currency other than your store's default, the order is created with the same amounts but in your default currency. For example, a checkout total of €227.46 appears in Wix as £227.46.

## Products

**How do I hide products or set up B2B-only products?**

A few options work well together:

- **Create a B2B-only page or collection** and send customers to it when they sign in. In the Wix editor, open the page's settings and, under **Permissions**, choose **Site members** and then **Specific members**. Turn on **Members with roles** and choose a member role, such as `B2B Customers`. See Wix's guide to [creating restricted store pages](https://support.wix.com/en/article/wix-stores-creating-restricted-store-pages).
- **Create B2B-only products** as separate products in Wix, each with its own SKU.
- **Leave products out of your price lists.** If a SKU has no B2B price, B2B customers can't buy it.

**How do I hide retail prices on my Wix store?**

Hide your retail prices in Wix, so prices only appear once a B2B customer signs in. This is one way to make your Wix store B2B-only. See Wix's guide to [hiding product prices](https://support.wix.com/en/article/wix-stores-hiding-product-prices).

**Can I base B2B prices on my Wix prices?**

Yes. An automatic price list can use your Wix prices (such as your retail price) and apply a discount, for example 20% off. It can also allow for your Wix tax setup, whether your prices include or exclude tax. See [Managing pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md).

**How do I set up pre-order and back-order products?**

Turn on **Pre-order** for the product in Wix; see [Pre-orders and pre-order limits](https://docs.sparklayer.io/help/platforms/wix/install.md#pre-orders-and-pre-order-limits). SparkLayer then shows a pre-order message to B2B customers. [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md) explains the stock messages and how to show "due in" dates.

**Do my products need SKUs?**

Yes. SparkLayer matches B2B prices to products by SKU, so a product without a unique SKU can't show B2B prices. You can add SKUs to products one at a time, or in bulk with Wix's product import or bulk edit. See [Add SKUs to your products](https://docs.sparklayer.io/help/platforms/wix/install.md#add-skus-to-your-products).

**How do I show stock levels?**

SparkLayer can show stock levels and a stock status to signed-in B2B customers. See [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md).

**Can I keep B2B and retail stock separate?**

Not on one store. When retail and B2B run from the same Wix store, they share the same stock, and Wix has no way to stop retail customers ordering from it. To separate stock, either create B2B-only products, or set up a separate Wix store for your B2B customers.

## Customer experience

**How do I set up a B2B registration form?**

You can add extra fields to your existing sign-up page, or create a separate registration page for B2B customers using [Wix Forms](https://support.wix.com/en/article/wix-forms-an-overview). To review applications yourself, add approved customers manually in **Customers & Leads > Contacts**. SparkLayer also has its own [Forms](https://docs.sparklayer.io/help/forms.md).

**How do I invite B2B customers to my store?**

You can use Wix's own messaging:

- **One customer:** open the contact in **Customers & Leads > Contacts**, go to the **Inbox** tab and send them a message, for example telling them to sign in to your store.
- **Several customers:** in **Customers & Leads > Contacts**, search or filter your contacts, select them and click **Send Email Campaign**.

The [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md) has example messages.

**Will SparkLayer slow down my Wix store?**

No. SparkLayer only loads when a B2B customer signs in; for retail customers, no SparkLayer code loads at all. For B2B customers, the widgets load asynchronously, so the effect on page load times is negligible.

**How do I show B2B-only content on my Wix store?**

We recommend talking to a Wix expert developer before making changes to your site.

## Orders

**Where do I find B2B orders in Wix?**

In **Sales > Orders**. The payment status depends on how the customer paid:

| Payment method | Payment status in Wix |
| --- | --- |
| **Pay on Account** | **Unpaid**. Mark the order as paid once you've received payment. |
| **Pay by Invoice** | **Unpaid**. Mark the order as paid once you've received payment. |
| **Pay Online by Card** | **Paid**, ready to fulfil. |
| **Request for Quote** | **Unpaid**. Mark the order as paid once you've received payment. |

In customer groups, **Pay Online by Card** is called **Card at checkout**. See [How B2B orders arrive in Wix](https://docs.sparklayer.io/help/platforms/wix/install.md#how-b2b-orders-arrive-in-wix).

**Why do orders show as Awaiting merchant?**

**Awaiting merchant** is the status a customer sees in their [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md#order-statuses) area for an order you haven't confirmed payment for yet. For example, you might still need to send an invoice.

To move it on, go to **Sales > Orders**, select the order and choose **More Actions > Mark as paid**. The status changes from **Awaiting merchant** to **Processing**, and you can fulfil the order as normal.

**Can I edit an order?**

Yes, as long as payment hasn't been processed. Open the order in **Sales > Orders**, click **More Actions** and choose **Edit order**.

**How do I send an invoice?**

SparkLayer doesn't send invoices itself, but Wix can. Open the order in **Sales > Orders**, click **More Actions** and choose **Create Invoice**. You collect payment your usual way, then mark the order as paid in Wix and fulfil it.

**How do I set a minimum order value?**

Set order limits for each customer group in **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app: a minimum or maximum order total, or a minimum or maximum number of items. See [Set order limits](https://docs.sparklayer.io/help/storefront/quantity-rules.md#order-limit-rules).

**How do I send order notifications to customers and my team?**

In your Wix dashboard, go to **Settings > Outgoing Notifications**.


---

# Limitations

URL: https://docs.sparklayer.io/help/platforms/wix/limitations
Applies to: Wix

What works differently on Wix: no product card pricing or metafields, one-time address sync, single-currency orders, Wix discounts, fees and tax exemptions.

> **Quick summary**
>
> - The biggest differences on Wix: no B2B prices on product cards, no metafields, and orders in one currency.
> - Customer addresses sync from Wix once, when the `b2b` label is first added.
> - Use SparkLayer's own [discounts](https://docs.sparklayer.io/help/pricing/discounts.md) and [shipping](https://docs.sparklayer.io/help/ordering/shipping-rules.md) rather than Wix discounts, additional fees or local delivery.

Some SparkLayer features depend on what Wix supports. This page lists what works differently on Wix. To check a feature across all platforms, see [Compare platforms](https://docs.sparklayer.io/help/platforms/compare.md).

## Products

| Limitation | Details |
| --- | --- |
| **Product cards (gallery)** | The [product card interface](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) isn't available on Wix. Where products are listed (such as your home page or a gallery page), B2B pricing is hidden. |
| **Metafields** | Wix doesn't support the [metafields](https://docs.sparklayer.io/developers/data/metafields.md) SparkLayer reads on other platforms, so features that rely on them, such as [pack sizes](https://docs.sparklayer.io/help/storefront/quantity-rules.md) and [RRP pricing](https://docs.sparklayer.io/help/pricing/pricing-display.md), aren't available. See [Wix metafields](https://docs.sparklayer.io/help/platforms/wix/metafields.md). |
| **Subscriptions** | Wix subscription programmes aren't supported. |
| **Loyalty** | Wix loyalty programmes aren't supported. |
| **Digital products** | Digital products in Wix aren't supported. |

## Pricing and discounts

| Limitation | Details |
| --- | --- |
| **Multi-currency** | A Wix store [can only accept one currency](https://support.wix.com/en/article/wix-stores-request-selling-in-multiple-currencies). If you create price lists in other currencies 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, signed-in B2B customers see prices in their price list's currency, at the exchange rate at that time. But an order placed in another currency is created in your store's default currency, with the same amounts. |
| **Discounts and coupons** | Wix's own discounts can't be used alongside SparkLayer. Use the SparkLayer [Discount Engine](https://docs.sparklayer.io/help/pricing/discounts.md) instead. |

## Customers

| Limitation | Details |
| --- | --- |
| **Customer address sync** | A customer's address syncs from Wix only once, when the `b2b` label is first added to the contact. Later changes to the contact's address in Wix don't sync to SparkLayer. Customers can add and edit addresses in the [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) address book. |
| **The `b2b` label** | SparkLayer needs the `b2b` label. You can rename it in Wix, but if you've already renamed a `b2b` label, a new label you create called `b2b` is saved by Wix as `b2b+x`. |
| **Customer group labels** | SparkLayer creates each group's label in Wix for you. Add that existing label to contacts. Don't create a new one with the same name: Wix saves it with a hidden suffix, such as `group-d-tYypo`, and the sync reports "Invalid customer group". |

## Checkout, shipping and tax

| Limitation | Details |
| --- | --- |
| **Custom checkout fields** | [Custom checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md) need a developer on Wix. They add them in code, with the `checkoutCustomElements` option in a `window.sparkWixOptions` script: see the [checkout field example](https://docs.sparklayer.io/help/platforms/wix/install.md#javascript-options). |
| **Additional fees** | Wix's [additional fees at checkout](https://support.wix.com/en/article/wix-functions-adding-additional-fees-at-checkout) aren't supported. |
| **Pickup and local delivery** | Wix [local delivery](https://support.wix.com/en/article/wix-stores-setting-up-local-delivery) isn't offered as a shipping option at checkout. Add it as a manual shipping method in SparkLayer [shipping](https://docs.sparklayer.io/help/ordering/shipping-rules.md) instead. |
| **Tax exemptions** | Tax exemptions only apply when the customer checks out through the Wix checkout (**Card at checkout**). With offline payment methods, such as Pay by Invoice, tax is charged at checkout. |


---

# Error codes

URL: https://docs.sparklayer.io/help/platforms/wix/error-codes
Applies to: Wix

Fix the SparkLayer error wix-checkout-out-of-stock on Wix, which appears when a product doesn't sync from Wix, for example because two products share a SKU.

When SparkLayer finds a problem with a Wix order, it shows an error code in [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md). Find the code below to see what it means and how to fix it.

## wix-checkout-out-of-stock

### What it means

A product in the cart is out of stock in Wix, but SparkLayer believes it's in stock. This happens when the product isn't syncing from Wix to SparkLayer, so its stock can't sync either. For example, another product may already have the same SKU.

### How to fix it

1. In the SparkLayer Dashboard, go to **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app.
2. Search for the product in **Product data lookup** to check it's syncing.
3. Give every product a unique SKU, so all your products sync.

See [Product and customer sync](https://docs.sparklayer.io/help/integrations/data-sync.md).

## Other errors

If you see an error that isn't listed here, see [Troubleshooting](https://docs.sparklayer.io/help/troubleshooting.md) or [contact our support team](https://docs.sparklayer.io/help/support.md).


---

# Metafields

URL: https://docs.sparklayer.io/help/platforms/wix/metafields
Applies to: Wix

Wix doesn't support SparkLayer metafields, so settings that rely on them, such as pack sizes and RRP pricing, aren't available on Wix stores.

> **Quick summary**
>
> - Wix doesn't support the metafields SparkLayer reads on other platforms, so you can't use them on a Wix store.
> - Settings that rely on metafields, such as [pack sizes](https://docs.sparklayer.io/help/storefront/quantity-rules.md) and [RRP pricing](https://docs.sparklayer.io/help/pricing/pricing-display.md), can't be used on a Wix store.
> - For other differences on Wix, see [Wix limitations](https://docs.sparklayer.io/help/platforms/wix/limitations.md).

## What metafields are

Metafields store extra information that your platform's admin doesn't usually capture, such as a product's pack size or RRP, or a customer's credit limit. On other platforms, SparkLayer reads them to change what B2B customers see and can order.

The [metafield settings](https://docs.sparklayer.io/developers/data/metafields.md) in the developer docs don't apply to Wix stores.


---

# Cancel or uninstall SparkLayer

URL: https://docs.sparklayer.io/help/platforms/wix/uninstall
Applies to: Wix

Cancel SparkLayer on Wix by deleting the app in Manage Apps, see what happens to billing and your data, and set SparkLayer up again on a new Wix store.

> **Quick summary**
>
> - To cancel SparkLayer, uninstall it like any other Wix app, from **Apps > Manage Apps**. This ends your subscription, and SparkLayer billing stops straight away.
> - Treat uninstalling as deleting your SparkLayer data. Export anything you need first, such as your price lists, and [contact our team](https://docs.sparklayer.io/help/support.md) first if you plan to reinstall.
> - You can't move a SparkLayer account to another Wix store: create a new account on the new store instead.
> - For plans, downgrading and refunds, see [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md).

> **Uninstalling deletes your SparkLayer data**
>
> Treat uninstalling as deleting your SparkLayer account: its price lists, customer groups and settings. Before you uninstall, export anything you want to keep, such as your [price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md). If you plan to reinstall, move to another store or need a [test store](https://docs.sparklayer.io/help/dashboard/test-mode.md), [contact our support team](https://docs.sparklayer.io/help/support.md) first, so we can talk through your options. Don't uninstall to change your plan: see [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md).

## Uninstall SparkLayer

Uninstall SparkLayer like any other Wix app.

1. In your Wix dashboard, go to **Apps > Manage Apps**.
2. Next to SparkLayer, click the **…** (more actions) button and choose **Delete**.

SparkLayer is removed from your store, your subscription ends, and its recurring billing is cancelled straight away. See Wix's guide to [deleting apps](https://support.wix.com/en/article/deleting-apps).

### What happens next

Treat uninstalling as deleting your SparkLayer data. SparkLayer stops receiving customer, product and order updates, and your account is scheduled for deletion, then deleted automatically after 30 days. 

Depending on when your SparkLayer billing cycle started, you may see charges you weren't expecting. See [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md) for refunds, or [contact us](https://docs.sparklayer.io/help/support.md) and we'll look into them.

## Move to another Wix store

You can't transfer a SparkLayer account to a different Wix store. Instead, install SparkLayer on the new store and create a new SparkLayer account. Export your [price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md) from the old account first, so you can upload them to the new one. See [Install SparkLayer on Wix](https://docs.sparklayer.io/help/platforms/wix/install.md).


---

# BigCommerce

URL: https://docs.sparklayer.io/help/platforms/bigcommerce
Applies to: BigCommerce

Add B2B and wholesale ordering to BigCommerce with the SparkLayer app: what works on BigCommerce, how setup works, its limitations and the demo store.

> **Quick summary**
>
> - The SparkLayer app adds B2B pricing, a B2B cart and an account area to your existing BigCommerce store. Retail (DTC) shoppers see your store as it is today.
> - SparkLayer needs BigCommerce customer groups, so it works on BigCommerce Plus, Pro and Enterprise. It's available on the Starter to Enterprise SparkLayer plans.
> - A customer becomes a B2B customer when they're in a BigCommerce customer group whose name starts with `B2B`.
> - Pre-orders, BigCommerce promotions and modifier options aren't available on BigCommerce: see [BigCommerce limitations](https://docs.sparklayer.io/help/platforms/bigcommerce/limitations.md).

## How SparkLayer works on BigCommerce

You install the [SparkLayer for BigCommerce app](https://www.bigcommerce.com/apps/sparklayer-b2b-wholesale/) from the BigCommerce Marketplace. SparkLayer then syncs your products, customers and B2B customer groups from BigCommerce.

The widgets go in your BigCommerce theme as a few code snippets. Our team adds them for you free of charge, or your developer can. You keep your theme, and can run retail and B2B from the same store.

You manage B2B prices and ordering rules in the [SparkLayer Dashboard](https://docs.sparklayer.io/help/dashboard.md). Products, customers and orders stay in BigCommerce.

## Install at a glance

Setting up SparkLayer on BigCommerce:

1. **Install the app**: From the BigCommerce Marketplace
2. **Create your account**: Register with SparkLayer and start your trial in BigCommerce
3. **Group customers**: Customer groups whose name starts with B2B
4. **Add the widgets**: Code snippets in your theme, added by our team or your developer
5. **Set prices and launch**: Price lists, customer group rules and a test order

The full steps are in [Install SparkLayer on BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce/install.md). Only the widgets need a developer, and our team can add them and an example price list for you, free of charge. See [Request free installation](https://docs.sparklayer.io/help/support.md#request-free-installation).

## What's specific to BigCommerce

| Topic | On BigCommerce |
| --- | --- |
| **Installing** | An app from the [BigCommerce Marketplace](https://www.bigcommerce.com/apps/sparklayer-b2b-wholesale/). |
| **B2B customers** | Customers in a BigCommerce customer group whose **Group Name** starts with `B2B`. |
| **Customer groups** | Synced from BigCommerce, so each B2B customer group in BigCommerce appears in SparkLayer. |
| **Widgets** | Code snippets added to your BigCommerce theme, by our team (free of charge) or by you or your developer. |
| **Orders** | Created in BigCommerce under **Orders**. Their status depends on the payment method. |
| **Billing** | Confirmed in BigCommerce when you install. |
| **Metafields** | Supported, using a metafields app or the BigCommerce API. Customer settings use customer attributes. |

## Limitations

The main differences from other platforms:

- Every product needs a unique SKU, and SparkLayer works best with stock tracked per variant.
- BigCommerce doesn't allow negative stock, so there are no pre-orders.
- BigCommerce promotions and modifier options can't be used with SparkLayer.

See [BigCommerce limitations](https://docs.sparklayer.io/help/platforms/bigcommerce/limitations.md) for the full list, including shipping, tax and multi-storefront, and [Compare platforms](https://docs.sparklayer.io/help/platforms/compare.md) to check a feature across platforms.

## Try the BigCommerce demo store

See SparkLayer on a working BigCommerce store that sells to both retail and B2B customers. Go to the [demo store's sign-in page](https://demo.bigcommerce.sparklayer.io/login.php) and sign in as a B2B customer with these details:

| Field | Value |
| --- | --- |
| **Email** | `bigcommerce+user@sparklayer.io` |
| **Password** | `Spark123^7&jj1` |

## BigCommerce guides

- [Install SparkLayer on BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce/install.md): Install the app, set up B2B customer groups and add the widgets to your theme
- [FAQs](https://docs.sparklayer.io/help/platforms/bigcommerce/faqs.md): Plans, themes, products and orders on BigCommerce
- [Limitations](https://docs.sparklayer.io/help/platforms/bigcommerce/limitations.md): What works differently, or isn't supported, on BigCommerce
- [Metafields and data mapping](https://docs.sparklayer.io/help/platforms/bigcommerce/metafields.md): Add pack sizes, RRP, credit limits and order data
- [Cancel, uninstall or transfer](https://docs.sparklayer.io/help/platforms/bigcommerce/uninstall.md): Cancel SparkLayer, take a break or move to another store


---

# Install SparkLayer on BigCommerce

URL: https://docs.sparklayer.io/help/platforms/bigcommerce/install
Applies to: BigCommerce

Install SparkLayer on BigCommerce: check requirements, add the app, set up B2B customer groups, add the widgets to your Stencil theme, then test an order.

> **Quick summary**
>
> - Install the SparkLayer app from the BigCommerce Marketplace and create your SparkLayer account. SparkLayer connects to your store and syncs your products and customers.
> - A customer becomes a B2B customer when they're in a BigCommerce customer group whose name starts with `B2B`.
> - The B2B widgets are code snippets in your BigCommerce theme. Our team adds them for you 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 BigCommerce:

1. **Before you start**: Customer accounts, SKUs, payments and shipping in BigCommerce
2. **Install**: Add the app and create your SparkLayer account
3. **Connect**: Create B2B customer groups so customers sync
4. **Widgets**: Add the code snippets 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?**
>
> Only for one step. You can do everything else yourself in your BigCommerce admin and the SparkLayer Dashboard. Adding the widgets means editing your theme's code: our team does it for you free of charge, or your developer can. Sections that need a developer are marked "for your developer".

## Before you start

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

- **BigCommerce Plus, Pro or Enterprise.** SparkLayer needs customer groups, which are available on these plans.
- **Customer accounts turned on** for your storefront, so customers can sign in. They're on by default; see BigCommerce's guide to [customer account creation](https://support.bigcommerce.com/s/article/Customer-Account-Creation?language=en_US).
- **A unique SKU on every product**, because SparkLayer stores B2B prices by SKU. See BigCommerce's guide to [product options and SKUs](https://support.bigcommerce.com/s/article/Product-Options-v2?language=en_US#skus).
- **A payment method.** On a test store, turn on an example [payment method](https://support.bigcommerce.com/s/article/Available-Payment-Gateways?language=en_US).
- **Shipping rules** set up in **Settings > Setup**, so orders can be placed from the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md) area. 

## Install SparkLayer

Install the app from the BigCommerce Marketplace, then create your SparkLayer account.

1. In your BigCommerce admin, go to **Apps > Marketplace** and search for **SparkLayer**.
2. Install the [SparkLayer app](https://www.bigcommerce.com/apps/sparklayer-b2b-wholesale/).
3. Create your SparkLayer account, or sign in if you already have one.
4. Confirm the SparkLayer billing plan in BigCommerce to start your free trial. 

## Connect your store

SparkLayer connects to your BigCommerce store as soon as you install the app, and starts syncing your products and customers. To finish connecting, set up your B2B customer groups.

To see your progress, go to **Apps > My Apps** and open **SparkLayer**. The **SparkLayer Setup** page lists your setup tasks, with a button for each:

- **Connect your BigCommerce store**
- **Upload your B2B pricing**
- **Set up your B2B customer groups**
- **Enable the storefront B2B widgets**
- **Test & Launch SparkLayer!**

The page also has **Install SparkLayer for me** and **Go to Dashboard** buttons.

In the SparkLayer Dashboard, click **Open Setup** on **Home** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale** in the Shopify app to see the steps still to do. **Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app shows **BigCommerce** as **Your platform**.

### Set up B2B customer groups

You create B2B customer groups in BigCommerce, not in SparkLayer. SparkLayer syncs only the groups whose name starts with `B2B`.

1. In your BigCommerce admin, go to **Customers > Customer Groups**.
2. Create a customer group, or edit an existing one.
3. Set the **Group Name** to start with `B2B`, for example `B2B - Default`, and save.
4. Add at least one customer to the group: open the customer and choose the group in **Customer Group**.

Once a `B2B` group has at least one customer, it appears in the SparkLayer Dashboard at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app, with this name and handle:

| Field | Format |
| --- | --- |
| **Name** | The exact group name from BigCommerce, for example `B2B - Default`. |
| **Handle (or ID)** | A numbered handle, such as `bigcommerce-group-1` or `bigcommerce-group-2`. You only need it for advanced integrations. |

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

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).

## Add the widgets

The SparkLayer widgets (the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md)) are code snippets in your BigCommerce theme. You don't have to edit any code yourself. Choose one option:

| Option | Best for |
| --- | --- |
| **Ask us to add them** (recommended) | Most merchants. Our team adds the widgets and an example B2B price list to your store free of charge, then arranges an onboarding call to walk you through it. 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**, or click **Install SparkLayer for me** on the SparkLayer Setup page in BigCommerce. See [Request free installation](https://docs.sparklayer.io/help/support.md#request-free-installation). |
| **Add them yourself** | You or your developer, if you're familiar with BigCommerce themes and Stencil, BigCommerce's [theme templating language](https://developer.bigcommerce.com/stencil-docs/overview). Follow the steps below. |

If our team is adding the widgets, skip to [Next steps](#next-steps).

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

These steps edit your theme's code. Pass them to your developer, or follow them yourself if you're comfortable with Stencil.

Edit your theme files in your BigCommerce admin at `yourstore.mybigcommerce.com/manage/channel/1/my-themes`. To try the changes before they go live, copy your theme first: go to **Channels > Themes**, open **Advanced** on your theme and choose **Make a Copy**. Edit the copy, then publish it when you're ready. 

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

The Core Script turns SparkLayer on in your store. Copy it from the [frontend integration guide](https://docs.sparklayer.io/developers/frontend.md) and replace `yourstorehere` with your store's [site ID](https://docs.sparklayer.io/help/dashboard/account.md). Then paste it inside the `<head>...</head>` tags of `/templates/layout/base.html`. The **Manually** option at **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app links to the same guide.

New installs use the latest Core Script version. To pin a version, choose it under **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 and click **Save version**.

**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="{{id}}"></spark-pdp>
```

The template is usually in `/templates/pages/`, for example `/templates/pages/product.html`. If your theme uses components, look in `/templates/components/products/product-view.html`. Depending on your theme, you may need to change the `id` variable, for example to `product.id`.

Display options for this widget, such as savings on price breaks and the RRP toggle, are at **Storefront > Options > Pricing and display** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options > Pricing and display** in the Shopify app. See [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md).

**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, so customers can add items to their order from anywhere. Add this snippet to the template that renders products on your collection pages:

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

This template is usually in `/templates/components/`, for example `/templates/components/products/card.html`. As with the product page, you may need to change `id` to `product.id`.

**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. See the [frontend integration guide](https://docs.sparklayer.io/developers/frontend.md).

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

To change the widgets' colours, fonts, spacing and button styles, override SparkLayer's CSS variables. Copy the [recommended starting CSS](https://docs.sparklayer.io/help/storefront/customising-design.md#recommended-starting-css) and add it inside the `<head>` of `/templates/layout/base.html`, or to a separate CSS file. See [Customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md).

**Step 6.** **Add the checkout script**

When a customer pays through the BigCommerce checkout, the checkout script tells SparkLayer the order is complete. SparkLayer then empties the customer's B2B order, so they can place another. Paste the checkout script at the very end of your order confirmation template, usually `/pages/order-confirmation.html`. [Contact us](https://docs.sparklayer.io/help/support.md) for the script for your store.

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 BigCommerce prices, for example 50% off retail. A manual one uses prices you upload by CSV, including quantity pricing. SparkLayer only uses price lists created in SparkLayer, and doesn't sync price lists from BigCommerce. See [Managing pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md).
2. **Add discounts (optional, Growth plan and above).** [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md) work on top of your price lists: a blanket discount, free products, or advanced discounts with requirements based on **SKU**, **BigCommerce Brand ID**, **BigCommerce Category IDs**, **BigCommerce Condition**, **BigCommerce UPC** or **BigCommerce Search Keywords**.
3. **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. The base customer group's rules apply to every B2B customer unless another group overrides them. See [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md).
4. **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 BigCommerce](#how-b2b-orders-arrive-in-bigcommerce).
5. **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 invite your customers. See [Invite a buyer](https://docs.sparklayer.io/help/customers/invite-buyers.md) and the [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md).

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

## Use SparkLayer Forms on BigCommerce

[SparkLayer Forms](https://docs.sparklayer.io/help/forms.md) work on BigCommerce, for example for trade account applications. Paste the form's embed code into your registration page: see [Add a form to your store](https://docs.sparklayer.io/help/forms/embedding-and-styling.md#add-a-form-to-your-store) (the **Other platforms** tab). When you approve an application, the customer is created in BigCommerce.

- **Load the form script only where you need it.** It only needs to be on the registration page, not in your theme's header, and you can load it with `defer`, for example `<script defer src="…">`.
- **Check the applicant isn't already a customer.** Approval fails if a customer with that email already exists in BigCommerce. Add the existing customer to a `B2B` group in BigCommerce instead.
- **Ask for a state or region where it's needed.** Some countries, such as Australia, need a state or region on both the billing and delivery address. If one is missing, [edit the entry](https://docs.sparklayer.io/help/forms/entries.md#edit-an-entry) to add it before you approve.
- **Tell approved customers how to set a password.** A SparkLayer form can't set a BigCommerce password. Customise the approval email (the **Send email** step in the form's [workflow](https://docs.sparklayer.io/help/forms/workflows.md)) to link to your store's login or reset password page.

## How B2B orders arrive in BigCommerce

The order's status in BigCommerce depends on the [payment method](https://docs.sparklayer.io/help/ordering/payment-methods.md) the customer chose:

| Payment method | Order status in BigCommerce | Order confirmation email |
| --- | --- | --- |
| **Pay on Account** | `Awaiting Payment` | Sent |
| **Pay by Invoice** | `Awaiting Payment` | Sent |
| **Pay Online by Card** | `Awaiting Fulfillment` | Sent |
| **Request for Quote** | `Incomplete` | Not sent |

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**.

## FAQs and troubleshooting

**My customer group doesn't appear in SparkLayer**

Check that the group's name in BigCommerce starts with `B2B`, and that at least one customer is in the group. SparkLayer only syncs groups that meet both conditions.

**Can you add the widgets for me?**

Yes, free of charge. Click **Request installation** at **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app, or **Install SparkLayer for me** on the SparkLayer Setup page in BigCommerce. See [BigCommerce FAQs](https://docs.sparklayer.io/help/platforms/bigcommerce/faqs.md).

**Can I use my BigCommerce price lists?**

No. SparkLayer only uses price lists you create in SparkLayer. Changes to price lists in BigCommerce don't apply to SparkLayer.

**Where can I find more help?**

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


---

# FAQs

URL: https://docs.sparklayer.io/help/platforms/bigcommerce/faqs
Applies to: BigCommerce

Answers to common questions about SparkLayer on BigCommerce: plans and billing, development stores, themes, B2B-only products and managing B2B orders.

## Plans and billing

**Which SparkLayer plans can I use on BigCommerce?**

Every SparkLayer plan from Starter to Enterprise works with BigCommerce. See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md) and the [SparkLayer pricing page](https://www.sparklayer.io/pricing/).

**How does billing work?**

When you sign up, our team contacts you to discuss the most suitable plan. Billing is monthly, with the option to pay annually.

**How do I choose or change my plan?**

You can install SparkLayer on BigCommerce without choosing a plan first. Our team then contacts you about next steps. Once your plan is active, we can move you up or down a plan as your needs change.

## BigCommerce setup

**Where do I find the SparkLayer BigCommerce app?**

In the [BigCommerce App Marketplace](https://www.bigcommerce.com/apps/sparklayer-b2b-wholesale/). See [Install SparkLayer on BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce/install.md).

**Which BigCommerce plan do I need?**

SparkLayer needs BigCommerce customer groups, so it works on BigCommerce Plus, Pro and Enterprise. You need an active BigCommerce store.

**Can I use SparkLayer on a development store?**

Yes. On a development or test store, we can turn on a developer mode so you can use SparkLayer before you start a billing plan. [Contact us](https://docs.sparklayer.io/help/support.md) to set this up.

**Can I run retail (DTC) and B2B on the same store?**

Yes. You can install SparkLayer on your existing retail BigCommerce store and run both from it. We call this a hybrid setup. When B2B customers sign in, they see the SparkLayer [frontend interfaces](https://docs.sparklayer.io/help/storefront.md) with their prices and ordering options. Try it on our [BigCommerce demo store](https://docs.sparklayer.io/help/platforms/bigcommerce.md#try-the-bigcommerce-demo-store).

## Store setup

**Can you install SparkLayer on my BigCommerce store for me?**

Yes, free of charge. To ask our team, click **Request installation** at **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app, or **Install SparkLayer for me** in the app in BigCommerce. We can usually do this within 1–2 working days. We then offer an onboarding session to walk you through how everything works. See [Request free installation](https://docs.sparklayer.io/help/support.md#request-free-installation).

**Does SparkLayer work with any BigCommerce theme?**

Yes, SparkLayer works with all BigCommerce themes, including fully customised ones. Our team can add the code snippets for you, free of charge.

**How does SparkLayer affect my BigCommerce theme?**

The SparkLayer widgets (B2B pricing, the cart and the My Account area) only load when a customer in a B2B customer group signs in. Everyone else sees your store as it is today, so you control exactly who sees B2B prices and can place B2B orders.

**I already use a wholesale or B2B app. Can I still use SparkLayer?**

Yes. SparkLayer can run alongside it, so you can try SparkLayer first and uninstall the other app when you're ready. If the other app changed your theme's code, you can ask its developer to remove those changes, but you don't have to.

## Payments

**Can customers use my existing BigCommerce payment methods?**

Yes, when they choose **Pay Online by Card** at the SparkLayer checkout. They're then taken to the BigCommerce checkout, which shows every payment method you've set up in BigCommerce (such as PayPal or Affirm). Any payment method BigCommerce supports can be used this way.

## Products

**How do I hide products or set up B2B-only products?**

A few options work well together:

- **Limit what a customer group can see.** In BigCommerce, edit the customer group and, under **Group Access**, untick **Customers in this group can see products in all categories across all channels**. Then tick only the categories the group should see.
- **Create a B2B-only collection** and send customers to it when they sign in. B2B-only products need to be separate products in BigCommerce, each with its own SKU.
- **Leave products out of your price lists.** If a SKU has no B2B price, B2B customers can't buy it.
- **Customise your theme** to hide or show products with custom code.
- **Hide products in SparkLayer** from every B2B customer or some customer groups, such as in the cart and [Catalog and Quick Order](https://docs.sparklayer.io/help/sales-ordering/catalog.md), with the `sparklayer.settings` metafield. See [Hide products from customers](https://docs.sparklayer.io/help/guides/hide-products.md).

**Can I base B2B prices on my BigCommerce prices?**

Yes. An automatic price list can use your BigCommerce prices (such as your retail price) and apply a discount, for example 20% off. It can also allow for your BigCommerce tax setup, whether your prices include or exclude tax. See [Managing pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md).

**How do I set up pre-order and back-order products?**

You can't on BigCommerce. BigCommerce doesn't allow stock to go below zero, so SparkLayer can't take orders for stock that isn't available yet. See [BigCommerce limitations](https://docs.sparklayer.io/help/platforms/bigcommerce/limitations.md#products-and-stock).

You can still show stock status messages and "due in" dates, so customers know when stock arrives. See [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md).

**Do my products need SKUs?**

Yes. SparkLayer matches B2B prices to products by SKU, so a product without a unique SKU can't show B2B prices. You can add SKUs to products one at a time, or in bulk with BigCommerce's product import or bulk edit.

**Can I keep B2B and retail stock separate?**

Not completely. When retail and B2B run from the same store, they share the same stock. SparkLayer can [reserve stock](https://docs.sparklayer.io/help/storefront/stock-display.md#reserving-stock) for retail customers, which stops B2B customers ordering too much of a product. But BigCommerce has no way to stop retail customers ordering from your stock.

To separate stock fully, either create B2B-only products, or set up a separate store for your B2B customers.

**Can I sell products on two storefronts?**

Yes, if you use both storefronts for wholesale. Edit the product in your BigCommerce admin and select both storefronts as sales channels. See also the multi-storefront notes in [BigCommerce limitations](https://docs.sparklayer.io/help/platforms/bigcommerce/limitations.md).

## Customer experience

**How do I set up a B2B registration form?**

Use [SparkLayer Forms](https://docs.sparklayer.io/help/forms.md): build an application form, embed it on your registration page, and approve each applicant into a customer group. See [Use SparkLayer Forms on BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce/install.md#use-sparklayer-forms-on-bigcommerce) for what's different on BigCommerce.

You can also customise your existing registration page with custom code, or use one of BigCommerce's [recommended form builder apps](https://support.bigcommerce.com/s/article/Creating-a-Contact-Form?language=en_US#form-builders). To review applications yourself, add approved customers manually in **Customers**.

**How do I invite B2B customers to my store?**

See [Customers](https://docs.sparklayer.io/help/customers.md) and the [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md).

**Will SparkLayer slow down my BigCommerce store?**

No. SparkLayer only loads when a B2B customer signs in; for retail customers, no SparkLayer code loads at all. For B2B customers, the widgets load asynchronously, so the effect on page load times is negligible.

**How do I show B2B-only content on my store?**

We recommend talking to a BigCommerce expert developer before changing your theme. They can use this Stencil code to show content only to signed-in B2B customers:

```html
{{#contains (toLowerCase customer_group_name) "b2b"}}

  <!-- This content will only show for logged in B2B customers -->

{{/contains}}
```

## Orders

**Where do I find B2B orders in BigCommerce?**

In **Orders**, like any other order. Their status depends on the payment method:

- **Card payments** (Pay Online by Card): **Awaiting Fulfillment**.
- **Offline payments** (Pay on Account and Pay by Invoice): **Awaiting Payment**. Update the status once you've received payment.
- **Quotes** (Request for Quote): **Incomplete**.

See [How B2B orders arrive in BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce/install.md#how-b2b-orders-arrive-in-bigcommerce).

**Why doesn't an order show as Shipped in SparkLayer?**

SparkLayer shows a B2B order as **Shipped** when both of these are true in BigCommerce:

- The order is marked as **Shipped**.
- The order has a shipment assigned to it.

Until then, the order stays as **Processing**.

**Can I edit an order?**

Yes. Open the order in **Orders** in your BigCommerce admin and edit it as you would any other order, before it's fulfilled.

**How do I send an invoice?**

SparkLayer doesn't send invoices itself. Use an invoicing app for BigCommerce, or send invoices from your existing finance system.

**Can I set a minimum order quantity?**

Yes. You can set minimum and maximum quantities for a product or a variant, including with BigCommerce's own **Minimum and Maximum Order Quantity** setting: see [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md). For the whole order, set order limits on a customer group in **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app: a minimum or maximum order total, or a minimum or maximum number of items. See [Set order limits](https://docs.sparklayer.io/help/storefront/quantity-rules.md#order-limit-rules).

**How do I send order notifications to customers and my team?**

In your BigCommerce admin, go to **Settings > Order Notifications**.


---

# Limitations

URL: https://docs.sparklayer.io/help/platforms/bigcommerce/limitations
Applies to: BigCommerce

What works differently on BigCommerce: unique SKUs, variant-level stock, no pre-orders, modifier options, multi-storefront, promotions, tax and shipping.

> **Quick summary**
>
> - The biggest differences on BigCommerce: no pre-orders, no BigCommerce promotions, and no modifier options in the widgets.
> - Every product needs a unique SKU, and SparkLayer works best with stock tracked per variant.
> - SparkLayer shipping only works if you turn off card payment through the BigCommerce checkout (**Card at checkout** in your customer groups).
> - BigCommerce multi-storefront isn't officially supported, though it works in most cases.

Some SparkLayer features depend on what BigCommerce supports. This page lists what works differently on BigCommerce. To check a feature across all platforms, see [Compare platforms](https://docs.sparklayer.io/help/platforms/compare.md).

## Products and stock

| Limitation | Details |
| --- | --- |
| **Product SKUs** | Every product must have a SKU, and it must be unique to that product. |
| **Product-level stock** | SparkLayer works with stock tracked per variant, so avoid tracking stock at product level where you can. If a product with several variants tracks stock at product level, SparkLayer shows the whole product's stock level against each variant. If a customer then adds variants whose total quantity is more than the product's stock, they see a "Something went wrong" error and can't continue. |
| **Negative stock and pre-orders** | BigCommerce doesn't allow stock to go below zero, so SparkLayer can't take pre-orders for stock that isn't available yet. The same applies to [quotes](https://docs.sparklayer.io/help/ordering/quoting.md): a quote can't be placed without enough stock to fulfil it. |
| **Modifier options** | BigCommerce modifier options (in the **Customizations** section when you edit a product) don't appear in the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md). SparkLayer only shows the variants set up in the product's **Variations** section, such as size or colour. |
| **Custom line items** | SparkLayer's custom line items feature isn't supported on BigCommerce. |

## Pricing and discounts

| Limitation | Details |
| --- | --- |
| **Price lists** | Price lists can only be managed in SparkLayer. Changes to price lists in BigCommerce don't apply to SparkLayer. |
| **Promotions** | BigCommerce discounts, such as order-level discounts and promotional codes, can't be used with SparkLayer. Use the SparkLayer [Discount Engine](https://docs.sparklayer.io/help/pricing/discounts.md) instead. We're reviewing this for a future update. |

## Customers and sales agents

| Limitation | Details |
| --- | --- |
| **Company users** | When a customer invites a team member as a [company user](https://docs.sparklayer.io/help/customers/company-users.md), the team member doesn't get a confirmation email. Tell them which email address to sign in with, and ask them to use **Forgot password** on your store to set a password. |

## Multi-storefront

SparkLayer doesn't officially support BigCommerce [multi-storefront](https://support.bigcommerce.com/s/article/Multi-Storefront?language=en_US). It works in most cases, with these limits:

- Only one customer with a given email address can exist across all the storefronts (channels) you use with SparkLayer.
- Products, customers and orders from every storefront share one SparkLayer site.
- A customer shares one SparkLayer site across all storefronts. To avoid invalid BigCommerce carts, either assign each customer to one storefront at a time, or make sure they finish checking out on one storefront before adding products on another.
- Each storefront needs its own numeric `igniteCheckoutContext.channel_id` value, set in an extra field in the SparkLayer Core Script options. This is a code change for your developer.

## Checkout, shipping and tax

| Limitation | Details |
| --- | --- |
| **Multi-zone tax** | SparkLayer supports multi-zone tax set up in BigCommerce, as long as at least one of these is true: **Prices entered with tax** is set to **No, I will enter prices exclusive of tax**, or **When calculating the taxes on sales made outside this storefronts default tax zone** is set to **Update product prices to reflect applicable tax rates**. |
| **Tax price display setting** | The **How are prices displayed on your storefront** setting affects how shipping costs appear in the cart. SparkLayer updates it automatically when you install the app or change the **Prices entered with tax** setting. If you change it on its own, SparkLayer isn't updated and shipping costs display incorrectly. [Contact us](https://docs.sparklayer.io/help/support.md) before you change it. |
| **SparkLayer shipping and card payments** | You can only use [SparkLayer shipping](https://docs.sparklayer.io/help/ordering/shipping-rules.md) on BigCommerce if **Card at checkout** is turned off in your customer groups' **Payment methods**. When an order goes through the BigCommerce checkout to pay online by card, BigCommerce replaces SparkLayer's shipping methods with your store's default shipping rules. |
| **Shipping cost display** | If your tax zone shows prices including tax, the costs in the SparkLayer cart's shipping method list use the cart's overall tax rate, not any shipping-specific tax rate. This only affects the costs shown in that list. The shipping cost in the cart summary comes from BigCommerce and is correct. |


---

# Metafields and data mapping

URL: https://docs.sparklayer.io/help/platforms/bigcommerce/metafields
Applies to: BigCommerce

Use BigCommerce metafields and customer attributes with SparkLayer for pack sizes, RRP and credit limits, import past orders and set custom order numbers.

> **Quick summary**
>
> - Metafields are optional. You don't need any to install SparkLayer or start taking B2B orders: add them only when you want a feature that uses one, such as pack sizes or credit limits.
> - Metafields hold extra B2B data in BigCommerce, such as a product's pack size or RRP. Customer settings, such as credit limits, use customer attributes instead.
> - Add product and order metafields with an app such as [Metafields Manager](https://www.bigcommerce.co.uk/apps/metafields-manager-by-space-48/), or the BigCommerce API.
> - Customer attributes for SparkLayer have to be created once per store with the BigCommerce API. This is a technical task for your developer, or [contact our support team](https://docs.sparklayer.io/help/support.md) for help.

## How SparkLayer uses metafields

[Metafields](https://docs.sparklayer.io/developers/data/metafields.md) store information that the BigCommerce admin doesn't usually capture. SparkLayer reads three kinds:

| Type | What SparkLayer uses it for |
| --- | --- |
| **Product metafields** | Settings for the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md), such as [pack sizes](https://docs.sparklayer.io/help/storefront/quantity-rules.md) and [RRP prices](https://docs.sparklayer.io/help/pricing/pricing-display.md). |
| **Customer attributes** | Customer settings, such as [credit limits](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md). |
| **Order metafields** | [Invoicing information](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) for an order. |

## Add product and order metafields

You don't need a developer for product and order metafields. Use a metafields app, such as the approved [Metafields Manager](https://www.bigcommerce.co.uk/apps/metafields-manager-by-space-48/) app. It can edit metafields on products, variants and orders, but not customers.

You can also use the BigCommerce API: see BigCommerce's [guide to product metafields](https://developer.bigcommerce.com/docs/rest-catalog/products/metafields).

## Things to know

- Product metafields are always added at variant level, even if a product only has one variant.
- Some SparkLayer settings must be entered as JSON, a structured text format. Their pages, such as [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md), have a **Build the value** form that writes it for you to copy.

For the settings each metafield controls, including customer-level product settings, see [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md).

## Add customer attributes (for your developer)

No BigCommerce app can add customer attributes, so they're created once per store with the BigCommerce API. This means running a command in a terminal. Pass these steps to your developer, or [contact our support team](https://docs.sparklayer.io/help/support.md) if you need help.

After that, the fields appear when you create or edit a customer in BigCommerce, and you fill them in without any code.

1. **Find your store hash.** It's the part of your admin URL between `store-` and `.mybigcommerce.com`. For example, in `store-vbnk8wgy6f.mybigcommerce.com`, the store hash is `vbnk8wgy6f`.
2. **Create an API account.** In your BigCommerce admin, go to **Settings > Store-level API accounts** and click **Create API Account**. Choose **V2/V3 API token** as the **Token type**, enter a **Name** you'll recognise (such as `SparkLayer Support`), and under **OAuth scopes**, set **Customers** to **modify**.
3. **Save the credentials.** Click **Save**. BigCommerce shows the credentials and downloads a copy to your computer. You need the **Access token**.
4. **Run the command.** Replace `YOUR_STORE_HASH` and `YOUR_STORE_API_TOKEN` in the command below, then run it in a terminal. You can remove any attributes you don't need.

```bash
curl --request POST \
  --url https://api.bigcommerce.com/stores/YOUR_STORE_HASH/v3/customers/attributes \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: YOUR_STORE_API_TOKEN' \
  --data '[
	{
		"name": "SparkLayer - Price Lists",
		"type": "string"
	},
	{
		"name": "SparkLayer - Payment On Account",
		"type": "string"
	},
	{
		"name": "SparkLayer - Accounting ID",
		"type": "string"
	},
	{
		"name": "SparkLayer - Discount Percentage",
		"type": "number"
	},
	{
		"name": "SparkLayer - Sales Agent Groups",
		"type": "string"
	},
	{
		"name": "SparkLayer - Parent Customer ID",
		"type": "string"
	}
]'
```

The customer create and edit pages then show a **Customer attribute fields** section with optional fields for **SparkLayer - Price Lists**, **SparkLayer - Payment On Account**, **SparkLayer - Accounting ID**, **SparkLayer - Discount Percentage**, **SparkLayer - Sales Agent Groups** and **SparkLayer - Parent Customer ID**.

## Import past orders

Import past B2B orders into SparkLayer, so customers see their order history when they sign in. Add this metafield to each order:

| Field | Value |
| --- | --- |
| **Namespace** | `sparklayer` |
| **Key** | `order_import` |
| **Value** | The string `true` |

Each imported order must belong to a customer in a B2B customer group. Add the metafield only after SparkLayer is installed. For a few orders, use a metafields app; for many, use the BigCommerce Order Metafields API.

Imported orders appear in the SparkLayer Dashboard and its order reports.

If SparkLayer was installed on your store before 14 November 2024, you may need to ask [our support team](https://docs.sparklayer.io/help/support.md) to re-save your BigCommerce integration. Re-saving registers the webhooks that tell SparkLayer when a metafield is added to an order.

## Show your own order numbers

Show customers your own order number, such as the one from your ERP, instead of the BigCommerce order number. Customers see it as the order **Reference** in their [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) area. Add this order metafield:

| Field | Value |
| --- | --- |
| **Custom data type** | Order |
| **Metafield type** | `single line text` |
| **Namespace** | `sparklayer` |
| **Key** | `visible_id` |

Orders without a `visible_id` show the standard BigCommerce order number.


---

# Cancel, uninstall or transfer SparkLayer

URL: https://docs.sparklayer.io/help/platforms/bigcommerce/uninstall
Applies to: BigCommerce

Cancel SparkLayer on BigCommerce by uninstalling the app, see what happens to billing and your data, take a break or move SparkLayer to another store.

> **Quick summary**
>
> - To cancel SparkLayer, uninstall it like any other BigCommerce app, from **Apps > My Apps**. This ends your subscription, and SparkLayer billing stops straight away.
> - Treat uninstalling as deleting your SparkLayer data. Export anything you need first, such as your price lists. Remove the widget code from your theme yourself.
> - Want to take a break, reinstall later or move to another BigCommerce store? [Contact our team](https://docs.sparklayer.io/help/support.md) before you uninstall.
> - For plans, downgrading and refunds, see [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md).

> **Uninstalling deletes your SparkLayer data**
>
> Treat uninstalling as deleting your SparkLayer account: its price lists, customer groups and settings. Before you uninstall, export anything you want to keep, such as your [price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md). If you plan to reinstall, [move to another BigCommerce store](#move-to-another-bigcommerce-store) or need a [test store](https://docs.sparklayer.io/help/dashboard/test-mode.md), [contact our support team](https://docs.sparklayer.io/help/support.md) first, so we can talk through your options. Don't uninstall to change your plan: see [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md).

## Uninstall SparkLayer

Uninstall SparkLayer like any other BigCommerce app.

1. In your BigCommerce admin, go to **Apps > My Apps**.
2. On the SparkLayer app, click **Uninstall**.

Your subscription ends, and SparkLayer's recurring billing is cancelled straight away. See BigCommerce's guide to [uninstalling apps](https://support.bigcommerce.com/s/article/How-do-I-access-and-install-the-new-single-click-apps-within-my-Bigcommerce-store-control-panel?language=en_US#uninstalling).

### What happens next

- **Widgets:** if you added the SparkLayer [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) to your theme, remove that code yourself or ask your developer.
- **Data:** treat uninstalling as deleting your SparkLayer data. SparkLayer stops receiving customer, product and order updates, and your account is scheduled for deletion, then deleted automatically after 30 days. 
- **Charges:** your subscription ends. Depending on when your billing cycle started, you may see charges you weren't expecting. See [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md) for refunds, or [contact us](https://docs.sparklayer.io/help/support.md) and we'll look into them.

## Pause your account

To stop using SparkLayer for a while and come back later, [contact our team](https://docs.sparklayer.io/help/support.md) before you uninstall anything. Uninstalling deletes your SparkLayer data, so we'll talk through the options for your account and plan first. See [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md).

If you do uninstall, keep a copy of your theme with the SparkLayer code as a backup, and export your [price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md) first.

## Move to another BigCommerce store

Your SparkLayer account is linked to one BigCommerce store URL. If you tried SparkLayer on a test or development store, you can move the account to another store. Because the move starts with uninstalling, [contact our support team](https://docs.sparklayer.io/help/support.md) before you start, and export anything you want to keep.

1. In the BigCommerce store you're leaving, [uninstall SparkLayer](#uninstall-sparklayer). This disconnects it from that store.
2. [Sign in to the SparkLayer Dashboard](https://app.sparklayer.io/Login) with your original account and 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.
3. Under **Your platform**, select **BigCommerce**, enter the URL of the new BigCommerce store and click **Save**. You're taken to the new store's BigCommerce admin.
4. Reinstall SparkLayer and choose a plan. You're returned to the SparkLayer Dashboard, and SparkLayer starts syncing the new store's products and customers.
5. Add the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) to the new store's theme.

If you need help moving stores, [contact us](https://docs.sparklayer.io/help/support.md).


---

# WooCommerce

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

Add B2B and wholesale ordering to WooCommerce with the SparkLayer plugin: what works on WooCommerce, how setup works, its limitations and the demo store.

> **Quick summary**
>
> - The SparkLayer plugin adds B2B pricing, a B2B cart and an account area to your existing WooCommerce store. Retail (DTC) shoppers see your store as it is today.
> - It works with WooCommerce 9 or later on WordPress 6 or later, with PHP 8.2 or later, on the Starter to Enterprise SparkLayer plans. WooCommerce support is in early access.
> - A customer becomes a B2B customer when their WordPress user has a `SparkLayer B2B` role.
> - Your store needs HTTPS and a permalink setting other than **Plain**: see [WooCommerce limitations](https://docs.sparklayer.io/help/platforms/woocommerce/limitations.md).

## How SparkLayer works on WooCommerce

You install the SparkLayer plugin on your WordPress site and connect it to SparkLayer with WooCommerce REST API keys. SparkLayer then syncs your products and B2B customers.

On a block theme, the plugin adds the widgets to your store automatically. On other themes, they go in your theme files: our team adds them free of charge, or your developer can. You keep your theme, and can run retail and B2B from the same store.

You manage B2B prices and ordering rules in the [SparkLayer Dashboard](https://docs.sparklayer.io/help/dashboard.md). Products, customers and orders stay in WooCommerce.

## Install at a glance

Setting up SparkLayer on WooCommerce:

1. **Install the plugin**: Upload it to your WordPress site
2. **Connect your store**: Register, then enter your store URL and REST API keys
3. **Assign roles**: Give B2B customers a SparkLayer B2B role
4. **Check the widgets**: Added automatically on block themes
5. **Set prices and launch**: Price lists, customer group rules and a test order

The full steps are in [Install SparkLayer on WooCommerce](https://docs.sparklayer.io/help/platforms/woocommerce/install.md). You only need a developer if your theme isn't a block theme. If you need help creating the API keys, [contact us](https://docs.sparklayer.io/help/support.md).

## What's specific to WooCommerce

| Topic | On WooCommerce | |
| --- | --- | --- |
| **Installing** | A WordPress plugin, connected with WooCommerce REST API keys. | |
| **B2B customers** | WordPress users with a `SparkLayer B2B` role, such as **SparkLayer B2B: Base**. | |
| **Customer groups** | Each SparkLayer customer group has a matching role in WordPress. | |
| **Widgets** | Added automatically on block themes; otherwise added to your theme files by our team (free of charge) or your developer. | |
| **Orders** | Created in WooCommerce under **Orders**, with a **SparkLayer Order Information** section. | |
| **Billing** | In the SparkLayer Dashboard, in the plan card at the foot of the sidebar. | |
| **Metafields** | Turned on in the SparkLayer Dashboard, at **Integrations > Platform > Metafields** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Metafields** in the Shopify app. | |

## Limitations

The main differences from other platforms:

- Every product needs a unique SKU.
- Price lists can only be managed in SparkLayer.
- The plugin only works on stores with HTTPS turned on and a WordPress permalink setting other than **Plain**.

See [WooCommerce limitations](https://docs.sparklayer.io/help/platforms/woocommerce/limitations.md) for the full list, and [Compare platforms](https://docs.sparklayer.io/help/platforms/compare.md) to check a feature across platforms.

## Try the WooCommerce demo store

See SparkLayer on a working WooCommerce store that sells to both retail and B2B customers. Go to the [demo store's My account page](https://demo.woocommerce.sparklayer.io/my-account/) and sign in as a B2B customer with these details:

| Field | Value |
| --- | --- |
| **Email** | `woocommerce@sparklayer.io` |
| **Password** | `I6qxPvpww42#3hsz0hTC%U2b` |

## WooCommerce guides

- [Install SparkLayer on WooCommerce](https://docs.sparklayer.io/help/platforms/woocommerce/install.md): Install the plugin, connect your store and assign B2B roles
- [FAQs](https://docs.sparklayer.io/help/platforms/woocommerce/faqs.md): Plans, themes, products and orders on WooCommerce
- [Limitations](https://docs.sparklayer.io/help/platforms/woocommerce/limitations.md): What works differently, or isn't supported, on WooCommerce
- [Metafields and data mapping](https://docs.sparklayer.io/help/platforms/woocommerce/metafields.md): Turn on pack sizes, RRP, credit limits and order data
- [Cancel, uninstall or transfer](https://docs.sparklayer.io/help/platforms/woocommerce/uninstall.md): Cancel SparkLayer or move it to another store


---

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


---

# FAQs

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

Answers to common questions about SparkLayer on WooCommerce: plans and billing, the plugin, themes, B2B-only products, stock, site speed and B2B orders.

## Plans and billing

**Which SparkLayer plans can I use on WooCommerce?**

Every SparkLayer plan from Starter to Enterprise works with WooCommerce. See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md) and the [SparkLayer pricing page](https://www.sparklayer.io/pricing/).

**How does billing work?**

You manage billing in the SparkLayer Dashboard: your plan is in the card at the foot of the sidebar (**Plan card** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Plan** in the Shopify app). Plans, free trials and billing follow the same rules as on Shopify.

## WooCommerce setup

**Where do I get the SparkLayer plugin?**

SparkLayer isn't in the WordPress plugin directory. [Register with SparkLayer](https://app.sparklayer.io/register) and download the plugin from [Install SparkLayer on WooCommerce](https://docs.sparklayer.io/help/platforms/woocommerce/install.md#install-sparklayer).

**Which versions of WooCommerce and WordPress do I need?**

[WooCommerce](https://woocommerce.com/) 9 or later, installed on WordPress 6 or later, with PHP 8.2 or later. WooCommerce support is in early access.

**Can I run retail (DTC) and B2B on the same store?**

Yes. You can install SparkLayer on your existing retail WooCommerce store and run both from it. We call this a hybrid setup. When B2B customers sign in, they see the SparkLayer [frontend interfaces](https://docs.sparklayer.io/help/storefront.md) with their prices and ordering options. Try it on our [B2B and retail demo store](https://demo.woocommerce.sparklayer.io/).

## Store setup

**Can you install SparkLayer on my WooCommerce store for me?**

On a block theme, the SparkLayer widgets are installed automatically. If you need help, [contact our support team](https://docs.sparklayer.io/help/support.md) and we'll advise you.

**Does SparkLayer work with any WooCommerce theme?**

Yes, as long as you're on WooCommerce 9 or later and WordPress 6 or later. On a block theme, the widgets are added automatically. On other themes, they're added to your theme files by you or your developer, or our team can help. See [Add the widgets](https://docs.sparklayer.io/help/platforms/woocommerce/install.md#add-the-widgets).

**How does SparkLayer affect my WooCommerce theme?**

The SparkLayer widgets (B2B pricing, the cart and the My Account area) only load when a customer in a B2B customer group signs in. Everyone else sees your store as it is today, so you control exactly who sees B2B prices and can place B2B orders.

**I already use a wholesale or B2B plugin. Can I still use SparkLayer?**

Yes. SparkLayer can run alongside it, so you can try SparkLayer first and remove the other plugin when you're ready. If the other plugin changed your theme's code, you can ask its developer to remove those changes, but you don't have to.

## Payments

**Can customers use my existing WooCommerce payment methods?**

Yes, when they choose **Pay Online by Card** at the SparkLayer checkout. They're then taken to the WooCommerce checkout, which shows every payment method you've set up in WooCommerce (such as PayPal or Affirm). Any payment method WooCommerce supports can be used this way.

## Products

**How do I hide products or set up B2B-only products?**

Create a B2B-only collection and send customers to it when they sign in. You can also customise your theme to hide or show products by tag, with custom code.

To hide products from B2B customers or some customer groups in SparkLayer, such as in the cart and [Catalog and Quick Order](https://docs.sparklayer.io/help/sales-ordering/catalog.md), use the `sparklayer.settings` metafield: see [Hide products from customers](https://docs.sparklayer.io/help/guides/hide-products.md).

**Can I base B2B prices on my WooCommerce prices?**

Yes. An automatic price list can use your WooCommerce prices (such as your retail price) and apply a discount, for example 20% off. It can also allow for your WooCommerce tax setup, whether your prices include or exclude tax. See [Managing pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md).

**How do I set up pre-order and back-order products?**

SparkLayer supports different stock status messages, including pre-orders and back orders, with some configuration in WooCommerce. See [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md), which also covers "due in" dates.

**Do my products need SKUs?**

Yes. SparkLayer matches B2B prices to products by SKU, so a product without a unique SKU can't show B2B prices. You can add SKUs to products one at a time, or in bulk with WooCommerce's product import. See [Add SKUs to your products](https://docs.sparklayer.io/help/platforms/woocommerce/install.md#add-skus-to-your-products).

**How do I show stock levels?**

SparkLayer can show stock levels and a stock status to signed-in B2B customers. See [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md) and [Stock levels](https://docs.sparklayer.io/help/platforms/woocommerce/install.md#stock-levels) for the WooCommerce settings.

**Can I keep B2B and retail stock separate?**

Not on one store. When retail and B2B run from the same WooCommerce store, they share the same stock, and WooCommerce has no way to stop retail customers ordering from it. To separate stock, either create B2B-only products, or set up a separate store for your B2B customers.

## Customer experience

**How do I set up a B2B registration form?**

You can add extra fields to your existing registration page, or create a separate registration page for B2B customers. To review applications yourself, add approved customers manually in **Users** in WordPress. SparkLayer also has its own [Forms](https://docs.sparklayer.io/help/forms.md).

**How do I invite B2B customers to my store?**

Send your customers a newsletter, for example, telling them about your B2B store and asking them to sign in. The [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md) has example messages.

**Will SparkLayer slow down my WooCommerce store?**

No. SparkLayer only loads when a B2B customer signs in; for retail customers, no SparkLayer code loads at all. For B2B customers, the widgets load asynchronously, so the effect on page load times is negligible.

**How do I show B2B-only content on my store?**

It's possible with custom code. We recommend talking to a WooCommerce expert developer before changing your site.

## Orders

**Where do I find B2B orders in WooCommerce?**

In **WooCommerce > Orders**. The status depends on how the customer paid:

| Payment method | Order status in WooCommerce |
| --- | --- |
| **Pay on Account** | **Pending payment**. Mark the order as paid once you've received payment. |
| **Pay by Invoice** | **Pending payment**. Mark the order as paid once you've received payment. |
| **Pay Online by Card** | **Completed**, ready to fulfil. |

In customer groups, **Pay Online by Card** is called **Card at checkout**. See [How B2B orders arrive in WooCommerce](https://docs.sparklayer.io/help/platforms/woocommerce/install.md#how-b2b-orders-arrive-in-woocommerce).

**Can I edit an order?**

Yes, as long as payment hasn't been processed. Open the order in **WooCommerce > Orders** and choose **Edit order**.

**How do I send an invoice?**

SparkLayer doesn't send invoices itself. Send invoices your usual way and collect payment, then mark the order as paid in WooCommerce and fulfil it.

**How do I set a minimum order value?**

Set order limits for each customer group in **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app: a minimum or maximum order total, or a minimum or maximum number of items. See [Set order limits](https://docs.sparklayer.io/help/storefront/quantity-rules.md#order-limit-rules).


---

# Limitations

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

What works differently on WooCommerce: unique SKUs, price lists managed only in SparkLayer, company user invites, HTTPS and the permalink setting.

> **Quick summary**
>
> - The SparkLayer plugin needs HTTPS and a WordPress permalink setting other than **Plain**.
> - Every product needs a unique SKU, and price lists are managed only in SparkLayer.
> - Invited company users don't get a confirmation email, so tell them their sign-in email and ask them to use **Forgot password**.

Some SparkLayer features depend on what WooCommerce supports. This page lists what works differently on WooCommerce. To check a feature across all platforms, see [Compare platforms](https://docs.sparklayer.io/help/platforms/compare.md).

## Store requirements

| Limitation | Details |
| --- | --- |
| **HTTPS** | The SparkLayer B2B plugin only works on WooCommerce stores with HTTPS turned on. |
| **Permalink structure** | The plugin uses the WordPress and WooCommerce API, so it needs the WordPress permalink structure set to anything other than **Plain**. Change it at **Settings > Permalinks**. |

## Products and pricing

| Limitation | Details |
| --- | --- |
| **Product SKUs** | Every product must have a SKU, and it must be unique to that product. |
| **Price lists** | Price lists can only be managed in SparkLayer. |

## Customers and sales agents

| Limitation | Details |
| --- | --- |
| **Company users** | When a customer invites a team member as a [company user](https://docs.sparklayer.io/help/customers/company-users.md), the team member doesn't get a confirmation email. Tell them which email address to sign in with, and ask them to use **Forgot password** on your store to set a password. |


---

# Metafields and data mapping

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

Turn on SparkLayer product, customer and order metafields for WooCommerce in Integrations > Platform, to add pack sizes, RRP prices and credit limits.

> **Quick summary**
>
> - Metafields are optional. You don't need any to install SparkLayer or start taking B2B orders: add them only when you want a feature that uses one, such as pack sizes or credit limits.
> - Metafields hold extra B2B data in WooCommerce, such as a product's pack size or RRP, or a customer's credit limit.
> - You choose which SparkLayer metafields to use in the SparkLayer Dashboard, at **Integrations > Platform > Metafields** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Metafields** in the Shopify app.

## How SparkLayer uses metafields

[Metafields](https://docs.sparklayer.io/developers/data/metafields.md) store information that the WooCommerce admin doesn't usually capture. SparkLayer reads three kinds:

| Type | What SparkLayer uses it for |
| --- | --- |
| **Product metafields** | Settings for the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md), such as [pack sizes](https://docs.sparklayer.io/help/storefront/quantity-rules.md) and [RRP prices](https://docs.sparklayer.io/help/pricing/pricing-display.md). |
| **Customer attributes** | Customer settings, such as [credit limits](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md). |
| **Order metafields** | [Invoicing information](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) for an order. |

## Turn on metafields

Choose which SparkLayer metafields to use in the SparkLayer Dashboard. You don't need a developer for this.

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.
2. In the **Metafields** card, click **Configure** next to **SparkLayer metafields**.
3. Select the SparkLayer [metafields](https://docs.sparklayer.io/developers/data/metafields.md) you want to use.

## Things to know

- Product metafields are always added at variant level, even if a product only has one variant.
- Some SparkLayer settings must be entered as JSON, a structured text format. Their pages, such as [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md), have a **Build the value** form that writes it for you to copy.

For the settings each metafield controls, including customer-level product settings, see [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md).


---

# Cancel, uninstall or transfer SparkLayer

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

Cancel SparkLayer on WooCommerce by deactivating the SparkLayer B2B plugin, see what happens to billing and your data, or move SparkLayer to another store.

> **Quick summary**
>
> - To cancel SparkLayer, deactivate the **SparkLayer B2B** plugin in **Plugins > Installed Plugins**, like any other WordPress plugin. This ends your subscription, and SparkLayer billing stops straight away.
> - Treat uninstalling as deleting your SparkLayer data. Export anything you need first, such as your price lists. Remove any widget code from your theme yourself.
> - Planning to reinstall or move to another WooCommerce store? [Contact our team](https://docs.sparklayer.io/help/support.md) before you uninstall.
> - For plans, downgrading and refunds, see [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md).

> **Uninstalling deletes your SparkLayer data**
>
> Treat uninstalling as deleting your SparkLayer account: its price lists, customer groups and settings. Before you uninstall, export anything you want to keep, such as your [price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md). If you plan to reinstall, [move to another WooCommerce store](#move-to-another-woocommerce-store) or need a [test store](https://docs.sparklayer.io/help/dashboard/test-mode.md), [contact our support team](https://docs.sparklayer.io/help/support.md) first, so we can talk through your options. Don't uninstall to change your plan: see [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md).

## Uninstall SparkLayer

Uninstall SparkLayer like any other WordPress plugin.

1. In your WordPress admin, go to **Plugins > Installed Plugins**.
2. Under **SparkLayer B2B**, click **Deactivate**.

This ends your subscription and cancels SparkLayer's recurring billing straight away. See WordPress's guide to [deactivating or deleting a plugin](https://wordpress.com/support/plugins/deactivate-or-delete-a-plugin/).

### What happens next

- **Widgets:** if you added the SparkLayer [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) to your theme, remove that code yourself or ask your developer.
- **Data:** treat deactivating as deleting your SparkLayer data. SparkLayer stops receiving customer, product and order updates, and your account is scheduled for deletion, then deleted automatically after 30 days. 
- **Charges:** your subscription ends. Depending on when your billing cycle started, you may see charges you weren't expecting. See [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md) for refunds, or [contact us](https://docs.sparklayer.io/help/support.md) and we'll look into them.

## Move to another WooCommerce store

Your SparkLayer account is linked to one WooCommerce store URL. If you tried SparkLayer on a test or development store, you can move the account to another store. Because the move starts with uninstalling, [contact our support team](https://docs.sparklayer.io/help/support.md) before you start, and export anything you want to keep.

1. In the store you're leaving, [uninstall SparkLayer](#uninstall-sparklayer). This disconnects it from that store.
2. [Sign in to the SparkLayer Dashboard](https://app.sparklayer.io/Login) with your original account and 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.
3. Under **Your platform**, select **WooCommerce (early access)** and enter the URL of the new store.
4. Install SparkLayer on the new store and choose a plan. 
5. SparkLayer starts syncing the new store's products and customers. Add the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) to the new store if your theme needs them.

If you need help moving stores, [contact us](https://docs.sparklayer.io/help/support.md).


---

# Magento

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

Add B2B and wholesale ordering to Magento or Adobe Commerce with SparkLayer: what works on Magento, how setup works, its limitations and the demo store.

> **Quick summary**
>
> - The SparkLayer module adds B2B pricing, a B2B cart and an account area to your existing Magento store. Retail (DTC) shoppers see your store as it is today.
> - It works with Magento Open Source and Adobe Commerce 2.4.2 or later, and needs the SparkLayer Enterprise plan.
> - A customer becomes a B2B customer when they're in a Magento customer group synced from SparkLayer, such as **B2B: Base**.
> - Luma-based themes are supported out of the box; other themes need a Magento developer to add the widgets.

## How SparkLayer works on Magento

Your developer installs the SparkLayer Magento module, which your SparkLayer account manager gives you access to. You then create an integration that connects your store to SparkLayer. SparkLayer syncs your products and B2B customers, and creates a Magento customer group for each SparkLayer customer group.

On Luma-based themes, you switch the widgets on in the module's settings. On other themes, a developer adds them. You keep your theme, and can run retail and B2B from the same store.

You manage B2B prices and ordering rules in the [SparkLayer Dashboard](https://docs.sparklayer.io/help/dashboard.md). Products, customers and orders stay in Magento.

## Install at a glance

Setting up SparkLayer on Magento:

1. **Install the module**: Ask your account manager for access
2. **Connect your store**: Create the integration and enter its credentials in SparkLayer
3. **Assign groups**: Put B2B customers in a synced B2B group
4. **Add the widgets**: Switch on for Luma themes; a developer for others
5. **Set prices and launch**: Price lists, customer group rules and a test order

The full steps are in [Install SparkLayer on Magento](https://docs.sparklayer.io/help/platforms/magento/install.md). If you need help creating the integration, [contact us](https://docs.sparklayer.io/help/support.md).

## What's specific to Magento

| Topic | On Magento |
| --- | --- |
| **Installing** | A Magento module, from your SparkLayer account manager, connected with a Magento integration. |
| **B2B customers** | Customers in a Magento customer group synced from SparkLayer, such as **B2B: Base**. |
| **Customer groups** | Created in SparkLayer and synced to Magento with the prefix `B2B`. |
| **Widgets** | Switched on in the module's settings for Luma-based themes; added by a developer on other themes. |
| **Orders** | Created in Magento under **Sales > Orders**, with a **SparkLayer Order Information** tab. |
| **Billing** | In the SparkLayer Dashboard, in the plan card at the foot of the sidebar. Magento needs the Enterprise plan. |
| **Metafields** | Called attributes in Magento. Turned on in the SparkLayer Dashboard, at **Integrations > Platform > Metafields** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Metafields** in the Shopify app. |

## Limitations

The main differences from other platforms:

- You need the SparkLayer Enterprise plan.
- Magento's Multi-Source Inventory (MSI) module must be turned on.
- Every product needs a unique SKU, and price lists can only be managed in SparkLayer.

See [Magento limitations](https://docs.sparklayer.io/help/platforms/magento/limitations.md) for the full list, and [Compare platforms](https://docs.sparklayer.io/help/platforms/compare.md) to check a feature across platforms.

## Try the Magento demo store

See SparkLayer on a working Magento store that sells to both retail and B2B customers, at [demo.magento.sparklayer.io](https://demo.magento.sparklayer.io/). Go to the [demo store's sign-in page](https://demo.magento.sparklayer.io/customer/account/login/) and sign in with these details. They work for both a sales agent and a regular B2B customer:

| Field | Value |
| --- | --- |
| **Email** | `contact@sparklayer.io` |
| **Password** | `Testtest!` |

## Magento guides

- [Install SparkLayer on Magento](https://docs.sparklayer.io/help/platforms/magento/install.md): Install the module, connect your store and assign B2B groups
- [FAQs](https://docs.sparklayer.io/help/platforms/magento/faqs.md): Plans, setup, products and orders on Magento
- [Limitations](https://docs.sparklayer.io/help/platforms/magento/limitations.md): What works differently, or isn't supported, on Magento
- [Metafields and data mapping](https://docs.sparklayer.io/help/platforms/magento/metafields.md): Turn on attributes for pack sizes, RRP and credit limits
- [Cancel or uninstall](https://docs.sparklayer.io/help/platforms/magento/uninstall.md): Cancel SparkLayer by deleting the integration


---

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


---

# FAQs

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

Answers to common questions about SparkLayer on Magento: the Enterprise plan, getting the module, theme impact, B2B-only products, stock and B2B orders.

## Plans and billing

**Which SparkLayer plan do I need for Magento?**

The Enterprise plan. See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md) and the [SparkLayer pricing page](https://www.sparklayer.io/pricing/).

**How does billing work?**

You manage billing in the SparkLayer Dashboard: your plan is in the card at the foot of the sidebar (**Plan card** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Plan** in the Shopify app). Plans, free trials and billing follow the same rules as on Shopify.

## Magento setup

**Where do I get the SparkLayer Magento module?**

[Contact our support team](https://docs.sparklayer.io/help/support.md) for access to the module. Your developer then installs it: see [Install SparkLayer on Magento](https://docs.sparklayer.io/help/platforms/magento/install.md).

**Which versions of Magento are supported?**

- Magento Open Source, version 2.4.2 or later
- Adobe Commerce (Cloud), version 2.4.2 or later

**Can I run retail (DTC) and B2B on the same store?**

Yes. You can install SparkLayer on your existing retail Magento store and run both from it. We call this a hybrid setup. When B2B customers sign in, they see the SparkLayer [frontend interfaces](https://docs.sparklayer.io/help/storefront.md) with their prices and ordering options. Try it on our [Magento demo store](https://docs.sparklayer.io/help/platforms/magento.md#try-the-magento-demo-store).

## Store setup

**How does SparkLayer affect my Magento theme?**

The SparkLayer widgets (B2B pricing, the cart and the My Account area) only load when a customer in a B2B customer group signs in. Everyone else sees your store as it is today, so you control exactly who sees B2B prices and can place B2B orders.

**I already use a wholesale or B2B extension. Can I still use SparkLayer?**

Yes. SparkLayer can run alongside it, so you can try SparkLayer first and remove the other extension when you're ready. If the other extension changed your theme's code, you can ask its developer to remove those changes, but you don't have to.

## Payments

**Can customers use my existing Magento payment methods?**

Yes, when they choose **Pay Online by Card** at the SparkLayer checkout. They're then taken to the Magento checkout, which shows every payment method you've set up in Magento (such as PayPal or Affirm). Any payment method Magento supports can be used this way.

## Products

**How do I hide products or set up B2B-only products?**

Create a B2B-only collection and send customers to it when they sign in. You can also customise your theme to hide or show products by tag, with custom code.

To hide products from B2B customers or some customer groups in SparkLayer, such as in the cart and [Catalog and Quick Order](https://docs.sparklayer.io/help/sales-ordering/catalog.md), use the `sparklayer.settings` metafield: see [Hide products from customers](https://docs.sparklayer.io/help/guides/hide-products.md).

**Can I base B2B prices on my Magento prices?**

Yes. An automatic price list can use your Magento prices (such as your retail price) and apply a discount, for example 20% off. It can also allow for your Magento tax setup, whether your prices include or exclude tax. See [Managing pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md).

**Do my products need SKUs?**

Yes. SparkLayer matches B2B prices to products by SKU, so a product without a unique SKU can't show B2B prices. You can add SKUs to products one at a time, or in bulk with Magento's import or product editing tools.

**How do I show stock levels?**

SparkLayer can show stock levels and a stock status to signed-in B2B customers. See [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md) and [Stock levels](https://docs.sparklayer.io/help/platforms/magento/install.md#stock-levels) for the Magento setting.

**Can I keep B2B and retail stock separate?**

Not on one store. When retail and B2B run from the same Magento store, they share the same stock, and Magento has no way to stop retail customers ordering from it. To separate stock, either create B2B-only products, or set up a separate store for your B2B customers.

## Customer experience

**How do I set up a B2B registration form?**

You can add extra fields to your existing registration page, or create a separate registration page for B2B customers. To review applications yourself, add approved customers manually in **Customers** in the Magento admin. SparkLayer also has its own [Forms](https://docs.sparklayer.io/help/forms.md).

**How do I invite B2B customers to my store?**

Send your customers a newsletter, for example, telling them about your B2B store and asking them to sign in. The [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md) has example messages.

**Will SparkLayer slow down my Magento store?**

No. SparkLayer only loads when a B2B customer signs in; for retail customers, no SparkLayer code loads at all. For B2B customers, the widgets load asynchronously, so the effect on page load times is negligible.

**How do I show B2B-only content on my store?**

It's possible with custom code. We recommend talking to a Magento expert developer before changing your site.

## Orders

**Can I edit an order?**

Yes, as long as payment hasn't been processed. Open the order in **Sales > Orders** and choose **Edit order**.

**How do I send an invoice?**

SparkLayer doesn't send invoices itself. Send invoices your usual way and collect payment, then mark the order as paid in Magento and fulfil it.

**How do I set a minimum order value?**

Set order limits for each customer group in **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app: a minimum or maximum order total, or a minimum or maximum number of items. See [Set order limits](https://docs.sparklayer.io/help/storefront/quantity-rules.md#order-limit-rules).


---

# Limitations

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

What works differently on Magento: unique product SKUs, price lists managed only in SparkLayer, company user invites and the required MSI module.

> **Quick summary**
>
> - The Magento integration needs the SparkLayer Enterprise plan and Magento's Multi-Source Inventory (MSI) module.
> - Every product needs a unique SKU, and price lists are managed only in SparkLayer.
> - Invited company users don't get a confirmation email, so tell them their sign-in email and ask them to use **Forgot password**.

Some SparkLayer features depend on what Magento supports. This page lists what works differently on Magento. To check a feature across all platforms, see [Compare platforms](https://docs.sparklayer.io/help/platforms/compare.md).

## Store requirements

| Limitation | Details |
| --- | --- |
| **Plan** | The Magento integration needs the SparkLayer [Enterprise plan](https://docs.sparklayer.io/help/plans-and-features.md). |
| **Multi-Source Inventory (MSI)** | Your Magento store must have the MSI module turned on. |

## Products and pricing

| Limitation | Details |
| --- | --- |
| **Product SKUs** | Every product must have a SKU, and it must be unique to that product. |
| **Price lists** | Price lists can only be managed in SparkLayer. |

## Customers and sales agents

| Limitation | Details |
| --- | --- |
| **Company users** | When a customer invites a team member as a [company user](https://docs.sparklayer.io/help/customers/company-users.md), the team member doesn't get a confirmation email. Tell them which email address to sign in with, and ask them to use **Forgot password** on your store to set a password. |


---

# Metafields and data mapping

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

Turn on SparkLayer product, customer and order attributes for Magento in Integrations > Platform, to set pack sizes, RRP prices and credit limits.

> **Quick summary**
>
> - On Magento, SparkLayer's metafields are Magento attributes. The rest of the Help Center calls them metafields.
> - Attributes hold extra B2B data, such as a product's pack size or RRP, or a customer's credit limit. They're optional: you only need them for the features that use them.
> - You choose which SparkLayer attributes to use in the SparkLayer Dashboard, at **Integrations > Platform > Metafields** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Metafields** in the Shopify app.

## How SparkLayer uses attributes

Attributes store information that the Magento admin doesn't usually capture. SparkLayer reads three kinds:

| Type | What SparkLayer uses it for |
| --- | --- |
| **Product attributes** | Settings for the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md), such as [pack sizes](https://docs.sparklayer.io/help/storefront/quantity-rules.md) and [RRP prices](https://docs.sparklayer.io/help/pricing/pricing-display.md). |
| **Customer attributes** | Customer settings, such as [credit limits](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md). |
| **Order attributes** | [Invoicing information](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) for an order. |

## Turn on attributes

Choose which SparkLayer attributes to use in the SparkLayer Dashboard. You don't need a developer for this.

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.
2. In the **Metafields** card, click **Configure** next to **SparkLayer metafields**.
3. Select the SparkLayer [attributes](https://docs.sparklayer.io/developers/data/metafields.md) you want to use.

## Things to know

- Product attributes are always added at variant level, even if a product only has one variant.
- Some SparkLayer settings must be entered as JSON, a structured text format. Their pages, such as [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md), have a **Build the value** form that writes it for you to copy.

For the settings each attribute controls, including customer-level product settings, see [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md).


---

# Cancel or uninstall SparkLayer

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

Cancel SparkLayer on Magento by deleting the SparkLayer B2B integration, see what happens to billing and your data, and remove the frontend widgets.

> **Quick summary**
>
> - To cancel SparkLayer, delete the **SparkLayer B2B** integration in **System > Integrations**. This ends your subscription, and SparkLayer billing stops straight away.
> - Treat uninstalling as deleting your SparkLayer data. Export anything you need first, such as your price lists. Remove any widget code from your theme yourself.
> - Planning to reinstall or move to another store? [Contact our team](https://docs.sparklayer.io/help/support.md) first. For plans, downgrading and refunds, see [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md).

> **Uninstalling deletes your SparkLayer data**
>
> Treat uninstalling as deleting your SparkLayer account: its price lists, customer groups and settings. Before you uninstall, export anything you want to keep, such as your [price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md). If you plan to reinstall, move to another store or need a [test store](https://docs.sparklayer.io/help/dashboard/test-mode.md), [contact our support team](https://docs.sparklayer.io/help/support.md) first, so we can talk through your options. Don't uninstall to change your plan: see [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md).

## Uninstall SparkLayer

To uninstall SparkLayer, delete its integration in the Magento admin.

1. In the Magento admin, go to **System > Integrations**.
2. Next to **SparkLayer B2B**, click **Delete**.

This ends your subscription and cancels SparkLayer's recurring billing straight away.

### What happens next

- **Widgets:** if you added the SparkLayer [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) to your theme, remove that code yourself or ask your developer.
- **Data:** treat deleting the integration as deleting your SparkLayer data. SparkLayer stops receiving customer, product and order updates, and your account is scheduled for deletion, then deleted automatically after 30 days. 
- **Charges:** your subscription ends. Depending on when your billing cycle started, you may see charges you weren't expecting. See [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md) for refunds, or [contact us](https://docs.sparklayer.io/help/support.md) and we'll look into them.


---

# Compare platforms

URL: https://docs.sparklayer.io/help/platforms/compare

Check which SparkLayer features and integrations work on Shopify, BigCommerce, Wix, WooCommerce and Magento, and the plans and platform versions each supports.

> **Quick summary**
>
> - SparkLayer runs on Shopify, BigCommerce, Wix, WooCommerce (early access) and Magento (including Adobe Commerce). Price lists and most B2B features work the same on all five.
> - Shopify supports the most: every SparkLayer plan (including the free Basic plan), almost every feature below and every listed integration. Magento needs the Enterprise plan.
> - The main gaps: Wix has no metafields or product card pricing, and BigCommerce has no pre-orders.
> - Most integrations, such as Xero and QuickBooks Online, are Shopify-only. Linnworks works on every platform.

Use this page to check a feature works on your platform before you rely on it. It brings together each platform's install guide, FAQs and limitations page. For anything not listed, see your platform's limitations page.

> **How to read the tables**
>
> ✓ means the feature is documented as working on that platform. **Limited** means it works with restrictions, explained in the notes. ✗ means it isn't supported. **Not documented** means our guides don't yet confirm it either way, so [contact support](https://docs.sparklayer.io/help/support.md) before relying on it.

## Platforms and plans

| Topic | Shopify | BigCommerce | Wix | WooCommerce | Magento |
| --- | --- | --- | --- | --- | --- |
| Install guide | [Shopify](https://docs.sparklayer.io/help/platforms/shopify/install.md) | [BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce/install.md) | [Wix](https://docs.sparklayer.io/help/platforms/wix/install.md) | [WooCommerce](https://docs.sparklayer.io/help/platforms/woocommerce/install.md) | [Magento](https://docs.sparklayer.io/help/platforms/magento/install.md) |
| Supported platform versions | All Shopify plans, from Basic to Shopify Plus | BigCommerce Plus, Pro and Enterprise (customer groups are required) | Wix Editor and Wix Studio | WooCommerce 9+ on WordPress 6+, with PHP 8.2+ (early access) | Magento Open Source and Adobe Commerce 2.4.2+, with PHP 7.4+ |
| Where you manage SparkLayer | The SparkLayer Wholesale app in your Shopify admin, or the SparkLayer Dashboard | SparkLayer Dashboard | SparkLayer Dashboard | SparkLayer Dashboard | SparkLayer Dashboard |
| SparkLayer plans | All plans, including the free Basic plan | Starter to Enterprise | Starter to Enterprise | Starter to Enterprise | Enterprise only |
| Limitations | [Shopify limitations](https://docs.sparklayer.io/help/platforms/shopify/limitations.md) | [BigCommerce limitations](https://docs.sparklayer.io/help/platforms/bigcommerce/limitations.md) | [Wix limitations](https://docs.sparklayer.io/help/platforms/wix/limitations.md) | [WooCommerce limitations](https://docs.sparklayer.io/help/platforms/woocommerce/limitations.md) | [Magento limitations](https://docs.sparklayer.io/help/platforms/magento/limitations.md) |

For the features included on each plan, see [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).

## Features

Most B2B features work everywhere. The numbered notes below the table explain each **Limited** entry.

| Feature | Shopify | BigCommerce | Wix | WooCommerce | Magento |
| --- | --- | --- | --- | --- | --- |
| [Price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md) (automatic and CSV) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Metafields](https://docs.sparklayer.io/developers/data/metafields.md) (e.g. pack sizes, RRP) | ✓ | ✓ | ✗ | ✓ | ✓ |
| [Product card](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) (prices on collection pages) | ✓ | ✓ | ✗ | ✓ | ✓ |
| [Sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Company users](https://docs.sparklayer.io/help/customers/company-users.md) | ✓ | Limited¹ | Not documented | Limited¹ | Limited¹ |
| [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md) | ✓ | Limited² | Not documented | Not documented | Not documented |
| [Pre-orders and back-orders](https://docs.sparklayer.io/help/storefront/stock-display.md) | ✓ | ✗ | ✓ | ✓ | ✓ |
| [SparkLayer discounts](https://docs.sparklayer.io/help/pricing/discounts.md) | ✓³ | ✓³ | ✓³ | Not documented | Not documented |
| [SparkLayer shipping rates](https://docs.sparklayer.io/help/ordering/shipping-rules.md) | ✓ | Limited⁴ | ✓ | ✓ | ✓ |
| [Multi-currency price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md) | ✓ | Not documented | Limited⁵ | Not documented | Not documented |
| [Custom checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md) | ✓ | Not documented | Limited⁶ | Not documented | Not documented |
| Custom line items | Not documented | ✗ | Not documented | Not documented | Not documented |

1. When a customer invites a team member, the team member doesn't receive a confirmation email. Tell them their sign-in email address and ask them to use **Forgot password** to set a password.
2. BigCommerce doesn't allow out-of-stock items when a quote is created or edited.
3. Use SparkLayer's own discounts, which need the Growth plan or above. Shopify discounts, BigCommerce promotions and Wix discounts can't be used alongside SparkLayer.
4. SparkLayer shipping methods can't be used for orders that go through the BigCommerce checkout to pay online by card.
5. Wix stores accept a single currency. Customers see prices in their price list's currency, but orders are created in your store's default currency.
6. On Wix, custom checkout fields need a developer, who adds them in code with the `checkoutCustomElements` option. See [Wix limitations](https://docs.sparklayer.io/help/platforms/wix/limitations.md#checkout-shipping-and-tax).

## Integrations

Most integrations are Shopify-only.

| Integration | Shopify | BigCommerce | Wix | WooCommerce | Magento |
| --- | --- | --- | --- | --- | --- |
| [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md) | ✓ | ✗ | ✗ | ✗ | ✗ |
| [Xero](https://docs.sparklayer.io/help/integrations/accountancy/xero.md) | ✓ | ✗ | ✗ | ✗ | ✗ |
| [QuickBooks Online](https://docs.sparklayer.io/help/integrations/accountancy/quickbooks.md) | ✓ | ✗ | ✗ | ✗ | ✗ |
| [Brightpearl](https://docs.sparklayer.io/help/integrations/erps/brightpearl.md) | ✓ | ✗ | ✗ | ✗ | ✗ |
| [Cin7 Core](https://docs.sparklayer.io/help/integrations/erps/cin7-core.md) | ✓ | ✗ | ✗ | ✗ | ✗ |
| [Katana](https://docs.sparklayer.io/help/integrations/erps/katana.md) | ✓ | ✗ | ✗ | ✗ | ✗ |
| [Unleashed](https://docs.sparklayer.io/help/integrations/erps/unleashed.md) | ✓ | ✗ | ✗ | ✗ | ✗ |
| [Linnworks](https://docs.sparklayer.io/help/integrations/erps/linnworks.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Sufio](https://docs.sparklayer.io/help/integrations/customer-experience/sufio.md) | ✓ | ✗ | ✗ | ✗ | ✗ |
| [Intuitive Shipping](https://docs.sparklayer.io/help/integrations/customer-experience/intuitive-shipping.md) | ✓ | ✓ | ✗ | ✗ | ✗ |

An ✗ means the integration's requirements list only Shopify (or Shopify and BigCommerce). B2B Catalogs is a Shopify app.

## Other platforms

To connect another platform or a custom-built website to SparkLayer, use [SparkLayer Ignite](https://docs.sparklayer.io/ignite.md), our framework for building platform integrations. Ignite is part of the Enterprise plan.


---

# Integrations

URL: https://docs.sparklayer.io/help/integrations

See which ERP, inventory, accounting and shipping apps work with SparkLayer, what data each one syncs and how often, and how to connect it in the Dashboard.

> **Quick summary**
>
> - SparkLayer connects directly to **Brightpearl**, **Cin7 Core**, **Katana**, **Linnworks** and **Unleashed** (ERP and inventory), **Xero** and **QuickBooks Online** (accounting), and **Sufio** and **Intuitive Shipping** (customer experience). For other systems, see [If your app isn't listed](#if-your-app-isnt-listed).
> - Connect an app in the SparkLayer Dashboard at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app: turn on the switch next to it, then sign in to it or enter its key. In the Shopify app, **Partners** lists each app with a **Setup guide** button that opens its guide here.
> - ERPs send your B2B customers and prices into SparkLayer on a schedule. Accounting apps receive an invoice from SparkLayer for each B2B order paid by invoice or on account.
> - Xero and QuickBooks need the Pro plan, and the ERP integrations the Pro or Enterprise plan. The ERP and accounting integrations need a Shopify store, except Linnworks, which works on every platform. See [Compare platforms](https://docs.sparklayer.io/help/platforms/compare.md).

## How integrations work

Your eCommerce platform is always connected to SparkLayer, in **Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app. That's how SparkLayer knows your products and B2B customers: see [Platforms](https://docs.sparklayer.io/help/platforms.md).

A partner integration connects one more system you use, such as an ERP or accounting app. Depending on the app, it does one of 3 things:

- Sends SparkLayer your B2B customers and prices (ERPs).
- Receives your B2B orders as invoices (accounting apps).
- Adds something to the buying experience, such as invoices or shipping rates (customer experience apps).

How data flows with an ERP integration such as Cin7 Core or Unleashed:

1. **Your ERP**: You manage B2B customers and price lists here
2. **SparkLayer**: Imports customers and prices on a schedule
3. **Your store**: B2B customers sign in and see their prices
4. **Back to your ERP**: Orders reach most ERPs through their own store integration

## Apps SparkLayer works with

Find your app to see what data it moves, which way and how often, and whether it works on your plan and platform.

| Integration | Type | What moves, and which way | How often | Plan | Platforms |
| --- | --- | --- | --- | --- | --- |
| [Brightpearl](https://docs.sparklayer.io/help/integrations/erps/brightpearl.md) | ERP and operations | B2B customers and price lists, from Brightpearl into SparkLayer and Shopify. Orders reach Brightpearl through your existing Brightpearl integration. | Every 3 hours | Pro or Enterprise | Shopify |
| [Cin7 Core](https://docs.sparklayer.io/help/integrations/erps/cin7-core.md) | ERP and operations | Customers, their contacts and sell price tiers, from Cin7 Core into SparkLayer and Shopify. Orders reach Cin7 Core through your existing Cin7 integration. | Every hour | Pro or Enterprise | Shopify |
| [Katana](https://docs.sparklayer.io/help/integrations/erps/katana.md) | ERP and operations | B2B customers and price lists, from Katana into SparkLayer and Shopify. SparkLayer doesn't send orders to Katana. | Every 4 hours | Pro or Enterprise | Shopify |
| [Linnworks](https://docs.sparklayer.io/help/integrations/erps/linnworks.md) | ERP and operations | B2B prices, from Linnworks into SparkLayer. Customers stay on your platform. Orders reach Linnworks through your existing Linnworks integration. | Every hour | Pro or Enterprise | All platforms |
| [Unleashed](https://docs.sparklayer.io/help/integrations/erps/unleashed.md) | ERP and operations | Customers, sell price tiers and discounts, from Unleashed into SparkLayer and Shopify. Orders reach Unleashed through your existing Unleashed integration. | Every 4 hours | Pro or Enterprise | Shopify |
| [Xero](https://docs.sparklayer.io/help/integrations/accountancy/xero.md) | Accountancy | Invoices and contacts, from your B2B orders into Xero. Payments on those invoices come back to SparkLayer. | For each eligible order, shortly after it's placed | Pro or Enterprise | Shopify |
| [QuickBooks Online](https://docs.sparklayer.io/help/integrations/accountancy/quickbooks.md) | Accountancy | Invoices and customers, from your B2B orders into QuickBooks. | For each eligible order, shortly after it's placed | Pro or Enterprise | Shopify |
| [Sufio](https://docs.sparklayer.io/help/integrations/customer-experience/sufio.md) | Customer experience | Lets B2B customers view and download their Sufio invoices from My Account. | For each order | Needs a Sufio account | Shopify |
| [Intuitive Shipping](https://docs.sparklayer.io/help/integrations/customer-experience/intuitive-shipping.md) | Customer experience | Your Intuitive Shipping rates, shown in the SparkLayer checkout. | At checkout | Needs an Intuitive Shipping account | Shopify, BigCommerce |

## Connect an integration

Each app's guide has the full steps, but connecting one always starts the same way.

1. Check the app works on your plan and platform in [Apps SparkLayer works with](#apps-sparklayer-works-with).
2. Sign in to the [SparkLayer Dashboard](https://app.sparklayer.io/) and go to **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app. Partner apps can't be switched on inside the Shopify app.
3. Find the app under its type, for example **Multi-channel management** for ERPs or **Accountancy** for Xero and QuickBooks, and turn on the switch next to it.
4. Sign in to the app to give SparkLayer access, or enter the details it asks for, such as an API key (a code from the app that lets SparkLayer read your data).
5. Follow the rest of the app's guide, for example to tag the customers you want to import.

If your plan doesn't include the app, it shows the plan it needs and an **Unlock** button instead of a switch. See [Unlock a feature](https://docs.sparklayer.io/help/dashboard/plan-and-features.md#unlock-a-feature).

## Manage your integrations

To turn an integration on, change its settings or turn it off, see [Managing integrations](https://docs.sparklayer.io/help/integrations/managing-integrations.md). To check that products and customers are reaching SparkLayer, see [Product and customer sync](https://docs.sparklayer.io/help/integrations/data-sync.md).

## ERPs and operations

- [Brightpearl](https://docs.sparklayer.io/help/integrations/erps/brightpearl.md): Multi-channel eCommerce · Direct integration
- [Cin7 Core](https://docs.sparklayer.io/help/integrations/erps/cin7-core.md): ERP software · Direct integration
- [Linnworks](https://docs.sparklayer.io/help/integrations/erps/linnworks.md): Multi-channel eCommerce · Direct integration
- [Unleashed](https://docs.sparklayer.io/help/integrations/erps/unleashed.md): Inventory management · Direct integration
- [Katana](https://docs.sparklayer.io/help/integrations/erps/katana.md): Inventory management · Direct integration
- [Patchworks](https://www.sparklayer.io/partners-patchworks/): iPaaS solution · Trusted partner
- [Zynk](https://www.sparklayer.io/partners-zynk/): iPaaS solution · Trusted partner

## Accountancy

- [Xero](https://docs.sparklayer.io/help/integrations/accountancy/xero.md): Create invoices and import payments · Direct integration
- [QuickBooks Online](https://docs.sparklayer.io/help/integrations/accountancy/quickbooks.md): Create invoices from B2B orders · Direct integration

## Customer experience

- [Sufio invoicing](https://docs.sparklayer.io/help/integrations/customer-experience/sufio.md): Professional invoices · Direct integration
- [Intuitive Shipping](https://docs.sparklayer.io/help/integrations/customer-experience/intuitive-shipping.md): Advanced shipping · Direct integration

## If your app isn't listed

- **Patchworks** and **Zynk** are integration platforms (iPaaS): services that connect systems which don't have a direct SparkLayer integration. See their cards under [ERPs and operations](#erps-and-operations).
- Your developer or agency can build their own connection with the SparkLayer API. See [Building integrations](https://docs.sparklayer.io/developers/building-integrations.md).
- Not sure? [Contact support](https://docs.sparklayer.io/help/support.md) and tell us which system you use.


---

# Managing integrations

URL: https://docs.sparklayer.io/help/integrations/managing-integrations

Connect your eCommerce platform, set Shopify order actions and metafields, and connect or disconnect partner apps on the Platform and Partners screens.

> **Quick summary**
>
> - **Integrations** has **Platform** (your store connection, Shopify order actions and metafields) and **Partners** (ERP, accounting, invoicing and shipping apps). In the Shopify app they're tabs under **Integrations**.
> - Your store connection and **Auto-complete draft orders** are in **Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app.
> - Partner apps are listed in **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app. You switch them on in the SparkLayer Dashboard. In the Shopify app, each one has a **Setup guide** button instead.

## The Integrations pages

Each page covers one kind of connection:

| Page | What it's for |
| --- | --- |
| **Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app | Links SparkLayer to your eCommerce platform, so products and B2B customers sync automatically. It also holds **Shopify order actions** and **Metafields**. |
| **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app | Connects apps such as ERPs, accounting software and shipping tools. See [Integrations](https://docs.sparklayer.io/help/integrations.md) for the full list. |

To check your products are reaching SparkLayer, or look one up, go to **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app. See [Product and customer sync](https://docs.sparklayer.io/help/integrations/data-sync.md).

The storefront widgets are installed from **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app, not from Integrations. See [Storefront interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md).

## Check your platform connection

**Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app shows which store you're connected to, for example "Connected to Shopify: **your-store.myshopify.com**". When you change anything on this page, click **Save** in the save bar.

In the SparkLayer Dashboard, **Your platform** shows the platform you use and its store. In the Shopify app there's no platform choice: it's always Shopify.

| Platform | Supported versions |
| --- | --- |
| [Shopify](https://docs.sparklayer.io/help/platforms/shopify.md) | All versions, including Shopify Plus. |
| [BigCommerce](https://docs.sparklayer.io/help/platforms/bigcommerce.md) | BigCommerce Plus, Pro and Enterprise. |
| [Wix](https://docs.sparklayer.io/help/platforms/wix.md) | Wix Editor and Wix Studio. |
| [WooCommerce](https://docs.sparklayer.io/help/platforms/woocommerce.md) (early access) | WooCommerce 9+, WordPress 6+, PHP 8.2+. |
| [Magento](https://docs.sparklayer.io/help/platforms/magento.md) | Magento 2.4.2+, PHP 7.4+. |
| Other | Build your own integration with the SparkLayer API. See [Building integrations](https://docs.sparklayer.io/developers/building-integrations.md), or [contact us](https://docs.sparklayer.io/help/support.md). |

**Shopify only:**

To connect SparkLayer to a different Shopify store, change the **Shopify store**. Shopify then asks you to authorise the app again.

On every platform, you enter your store's connection details at **Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app. For full setup on each platform, see [Platforms](https://docs.sparklayer.io/help/platforms.md).

## Set Shopify order actions

**Shopify only:**

Orders paid with a manual method, such as Pay by Invoice, arrive in the Shopify admin as [draft orders](https://docs.sparklayer.io/help/glossary.md#draft-order). Order actions turn them into completed orders for you, and control Shopify's customer invite email. They're only available on Shopify.

1. Go to **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app.
2. Turn on the switches you want.
3. Click **Save**.

| Setting | What it does | Default |
| --- | --- | --- |
| **Auto-complete draft orders** | Turns draft orders from manual payments into completed orders automatically, so they appear in **Orders** in the Shopify admin instead of **Drafts**. | On |
| **Don't send Shopify's customer invite** | When a sales admin creates a customer in Shopify, skips Shopify's account invite email. See [Order for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md). | Off |

In the SparkLayer Dashboard, you'll also see 2 switches marked **SparkLayer staff only**: **Create a draft order on calculate** and **Draft orders with price overrides**. Only our team can change them. If you need line-item tax or use a shipping app that needs draft orders, [contact support](https://docs.sparklayer.io/help/support.md).

## Set up metafields

**Shopify only:**

On Shopify, SparkLayer can create the [metafields](https://docs.sparklayer.io/developers/data/metafields.md) it uses for you, so you don't have to set them up by hand in the Shopify admin. Metafields are extra fields on your Shopify products and customers, such as a product's pack size, that SparkLayer reads.

1. Go to **Integrations > Platform > Metafields** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Metafields** in the Shopify app.
2. Next to **SparkLayer metafields**, click **Configure**.
3. Turn on each metafield you want.

The metafields available for **Product** and **Customer** data include:

| Metafield | What it's for |
| --- | --- |
| **Pack Size** | Pack size rules for products, for example 6, 12, 18. |
| **Reserved DTC Stock Quantity** | A stock quantity to keep back for your retail (DTC) customers. |
| **Restock Date** | The date a product on pre-order is expected to be available. |
| **Stock Location Settings** | B2B stock settings, such as a minimum stock level and restock date, for specific stock locations. |

Each metafield you turn on is added to **Settings > Custom data** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data)) in the Shopify admin and pinned, so it shows at the top of a product's or customer's metafields. Its name starts with `B2B - `, for example `B2B - Pack Size`. To change or remove a metafield later, use **Custom data** in the Shopify admin.

## Connect or disconnect a partner app

**Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app lists the apps SparkLayer works with, grouped by type: **Multi-channel management**, **Accountancy**, **Invoicing** and **Shipping**. Each app's guide lists what you need before you start. See [Integrations](https://docs.sparklayer.io/help/integrations.md).

**SparkLayer Dashboard:**

1. Go to **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.
2. Turn on the switch next to the app.
3. Sign in to the app to authorise the connection, or enter the details it asks for, such as an API key.

A connected app shows **Connected**. To disconnect it, turn the switch off. Click **Learn more** next to an app for its guide.

**Shopify app:**

Partner apps can't be switched on inside Shopify. Each app has a **Setup guide** button that opens its guide in these docs. Follow the guide in the [SparkLayer Dashboard](https://app.sparklayer.io/).

Xero and QuickBooks need the Pro plan. Below Pro, they show **Pro** and an **Unlock** button instead of a switch: see [Unlock a feature](https://docs.sparklayer.io/help/dashboard/plan-and-features.md#unlock-a-feature).

To change an app's settings after you connect it, open it at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app. Its guide covers each setting.

If you need a hand with any of this, [contact support](https://docs.sparklayer.io/help/support.md).


---

# Product and customer sync

URL: https://docs.sparklayer.io/help/integrations/data-sync

Check your products are syncing to SparkLayer, look up a product's data, and find and fix customer sync errors on the Customers screen.

> **Quick summary**
>
> - SparkLayer keeps a copy of your products and B2B customers from your eCommerce platform, updated when you change them there. Only customers tagged `b2b` are imported, or customers your developer sends with SparkLayer [metafields](https://docs.sparklayer.io/help/glossary.md#metafields).
> - **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app shows whether your products are up to date and lets you look one up. On Shopify, its **Categories** card shows which collections buyers can filter [Catalog and Quick Order](https://docs.sparklayer.io/help/platforms/shopify/catalog-collections.md) by.
> - Customer sync problems show as a banner on **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app, with **Show errors** to see which customers need fixing. Your Home briefing flags them too.
> - To check a customer's data, open them in **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app.

## How sync works

Once your platform is connected (see [Managing integrations](https://docs.sparklayer.io/help/integrations/managing-integrations.md)), SparkLayer keeps two feeds from your store:

- **Product sync** tells SparkLayer which products and variants exist, so it knows which B2B prices to show when a signed-in B2B customer views a product.
- **Customer sync** tells SparkLayer who your B2B customers are, so it recognises them when they sign in and shows them the right B2B pricing and rules.

How product and customer data reaches your B2B customers:

1. **Your store**: Products, and customers tagged b2b
2. **Sync**: SparkLayer imports both feeds
3. **Price lists and customer groups**: Matched to products and customers
4. **Storefront**: Signed-in B2B customers see their prices

Each feed has a **full sync**, which copies everything, and **partial syncs**, which copy what's changed since. SparkLayer syncs every product in your store by default. A product can't be bought by B2B customers until it has a price: see [Pricing](https://docs.sparklayer.io/help/pricing.md).

## Check your products are syncing

Go to **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app. When everything is working, the banner at the top reads **Products are up to date**. It shows how many products synced from Shopify, and the times of the last full and partial sync.

SparkLayer refreshes products every 10 minutes, so you don't need to start a product sync yourself. If a change still hasn't shown after that, [contact support](https://docs.sparklayer.io/help/support.md). Our team can run a product sync for you from SparkLayer's staff-only tools.

**When to ask us for a full product sync**

Partial syncs pick up recent changes. A few problems need a full product sync, which our team runs for you. [Contact support](https://docs.sparklayer.io/help/support.md) if:

- You deleted a product and added it again, and it shows "Please ensure the variant slug is unique" or "Please ensure the variant SKU is unique", but the SKU isn't used anywhere else
- "SKU not unique" errors stay after you've made every SKU unique, for example after merging products into variants
- Variants you deleted on your platform still show to B2B customers or in **Product data lookup**
- You added a stock location, or imported a large batch of products, and products show as out of stock although they have stock
- Searching by SKU or barcode in the cart finds nothing, for products that are in **Product data lookup**

## Look up a product's data

**Product data lookup** shows what SparkLayer has for a product, to diagnose a price or stock question.

1. Go to **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app.
2. In **Product data lookup**, search by name, SKU, barcode or ID.
3. Check the results. Each shows the **Product**, its **SKU**, its **Retail price** and whether it's **Up to date**.

| Search by | Example or where to find it |
| --- | --- |
| **SKU** | The stock keeping unit of a variant. A product with three variants might have the SKUs `ABC-1`, `ABC-2` and `ABC-3`. |
| **ID** | The product's ID on your platform. On Shopify, open the product in the admin: the ID is the number at the end of the URL. In `https://your-shopify-store-url.com/admin/products/7356521840875` the ID is `7356521840875`. |
| **Name** | All or part of the product name. |
| **Barcode** | The barcode, if the product has one. |

If nothing comes back, it says **No products found**: try the SKU, or a different name. If a product still isn't there, see [Troubleshooting](https://docs.sparklayer.io/help/troubleshooting.md#the-product-data-sync-says-this-product-cannot-be-found).

**Stock states**

SparkLayer also holds each variant's stock. 

| Stock state | What it means |
| --- | --- |
| **Stock data found** | Stock information exists for this variant, for each location. |
| **Stock data not found** | SparkLayer has no stock data for this variant. Variants without stock data can't be bought. |
| **Stock not being tracked** | Inventory tracking is turned off for this variant on your platform, so there's no stock information. The variant can still be bought. |

## Check your customers are syncing

SparkLayer imports only customers tagged `b2b`, or customers your developer has sent with [metafields](https://docs.sparklayer.io/help/glossary.md#metafields) in the `sparklayer` namespace. That way, you control which customers are imported. On Shopify, see [Assign customers to a customer group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group) and [Shopify metafields](https://docs.sparklayer.io/help/platforms/shopify/metafields.md).

To check a customer has synced, find them in **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app and open them. Their page shows what SparkLayer holds: their details, customer group, company and addresses. See [Find and manage customers](https://docs.sparklayer.io/help/customers/managing-customers.md).

### Fix customer sync errors

When some customers didn't sync, **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app shows a banner such as **Customers sync completed with 3 errors**, with the times of the last full and partial sync.

1. Click **Show errors**. **Customer sync errors** lists each customer's name, email and the problem, such as "Missing a default shipping address".
2. Click **Open customers in Shopify** and fix each customer there.
3. Wait for the next partial sync. Fixed customers sync then.

From your first week, Home's [briefing](https://docs.sparklayer.io/help/dashboard.md#home) also tells you when customers didn't sync, with **Show errors**. Common errors and fixes are in [Troubleshooting](https://docs.sparklayer.io/help/troubleshooting.md#the-customer-data-sync-shows-errors).

If a customer or their address won't sync, these are the 2 most common causes:

| Cause | Fix |
| --- | --- |
| **An incomplete address**, often a secondary (second) address in the customer's address book | Complete the address in Shopify, with a country, first line, city and postcode or ZIP code, or delete it. Every address must be complete, not only the default one. |
| **The sales agent groups metafield isn't limited to preset choices** (Shopify) | Turn on **Limit to preset choices** on the metafield's definition, with each sales agent group as a choice. See [Set up the sales agent groups metafield](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#set-up-the-sales-agent-groups-metafield). |

**Re-running the customer sync**

You don't need to start a customer sync yourself: it runs automatically. If you think it's stuck, [contact support](https://docs.sparklayer.io/help/support.md). Our team can run **Sync customers now** for you from SparkLayer's staff-only tools.

## Troubleshooting

**The banner shows errors, or no products are syncing**

For product sync, check the products have a SKU on every variant and are **Active**. For customer sync, click **Show errors** on **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app. For common causes and fixes, see [Troubleshooting](https://docs.sparklayer.io/help/troubleshooting.md#data-sync). If you can't resolve it, [contact support](https://docs.sparklayer.io/help/support.md).

**A product can't be added to the cart**

Look the product up in **Product data lookup**. Also check the product has a price in one of the customer's [price lists](https://docs.sparklayer.io/help/pricing.md).

**A customer isn't recognised when they sign in**

Find them in **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app. If they aren't there, check they're tagged `b2b` on your platform (or, if your developer set them up that way, have `sparklayer` metafields), then check **Show errors** for a sync problem.

**I've changed products on my platform but SparkLayer hasn't updated**

Products refresh every 10 minutes. If they still haven't updated after that, [contact support](https://docs.sparklayer.io/help/support.md) and we'll run a product sync for you.


---

# ERPs and operations

URL: https://docs.sparklayer.io/help/integrations/erps

Connect SparkLayer to Brightpearl, Cin7 Core, Linnworks, Unleashed or Katana so B2B customers and prices sync from your ERP, or use Patchworks or Zynk.

> **Quick summary**
>
> - SparkLayer connects directly to **Brightpearl**, **Cin7 Core**, **Katana**, **Linnworks** and **Unleashed**. If your B2B customers and prices live in one of them, the integration keeps SparkLayer up to date without manual uploads.
> - Data goes one way: from your ERP into SparkLayer (and Shopify), on a schedule. B2B orders reach your ERP through the ERP's own connection to your store, not through SparkLayer. SparkLayer doesn't send orders to Katana.
> - Turn your ERP on in the SparkLayer Dashboard at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, under **Multi-channel management**, then follow its guide below. All five need the Pro or Enterprise plan. Linnworks works on every platform; the others need Shopify.
> - Using a different ERP? Patchworks and Zynk can connect it, or your developer can use the [SparkLayer API](https://docs.sparklayer.io/developers/api.md).

## How ERP integrations work

In most ERP integrations, the ERP becomes the source of truth for your B2B data: the one place you make changes.

1. You set up customers and prices in the ERP.
2. SparkLayer imports them on a schedule, and creates the matching customers and [price lists](https://docs.sparklayer.io/help/pricing.md).
3. B2B orders flow back to the ERP through its own connection to your store (except Katana: SparkLayer doesn't send orders to it).

Each ERP's guide follows the same pattern: what it does, what syncs and in which direction, how to set it up, and its limitations.

| Integration | Customers from the ERP | Prices from the ERP | How often | Orders to the ERP | Platforms |
| --- | --- | --- | --- | --- | --- |
| [Brightpearl](https://docs.sparklayer.io/help/integrations/erps/brightpearl.md) | Yes, by contact tag | Yes, from price lists | Every 3 hours | Through your Brightpearl–Shopify integration | Shopify |
| [Cin7 Core](https://docs.sparklayer.io/help/integrations/erps/cin7-core.md) | Yes, by customer tag | Yes, from sell price tiers and customer prices | Every hour | Through your Cin7–Shopify integration | Shopify |
| [Katana](https://docs.sparklayer.io/help/integrations/erps/katana.md) | Yes, by customer category | Yes, from price lists | Every 4 hours | No, SparkLayer doesn't send orders to Katana | Shopify |
| [Linnworks](https://docs.sparklayer.io/help/integrations/erps/linnworks.md) | No, customers stay on your platform | Yes, from extended properties | Every hour | Through your existing Linnworks integration | All platforms |
| [Unleashed](https://docs.sparklayer.io/help/integrations/erps/unleashed.md) | Yes, by customer type | Yes, from sell price tiers, customer pricing and discounts | Every 4 hours | Through your Unleashed–Shopify integration | Shopify |

## If your ERP isn't listed

- **Patchworks** and **Zynk** are integration platforms (iPaaS): services that connect systems which don't have a direct SparkLayer integration. Their cards below link to their partner pages.
- Your developer or agency can build a connection with the SparkLayer API. See [Building integrations](https://docs.sparklayer.io/developers/building-integrations.md).

## Choose your ERP

- [Brightpearl](https://docs.sparklayer.io/help/integrations/erps/brightpearl.md): Multi-channel eCommerce · Direct integration
- [Cin7 Core](https://docs.sparklayer.io/help/integrations/erps/cin7-core.md): ERP software · Direct integration
- [Linnworks](https://docs.sparklayer.io/help/integrations/erps/linnworks.md): Multi-channel eCommerce · Direct integration
- [Unleashed](https://docs.sparklayer.io/help/integrations/erps/unleashed.md): Inventory management · Direct integration
- [Katana](https://docs.sparklayer.io/help/integrations/erps/katana.md): Inventory management · Direct integration
- [Patchworks](https://www.sparklayer.io/partners-patchworks/): iPaaS solution · Trusted partner
- [Zynk](https://www.sparklayer.io/partners-zynk/): iPaaS solution · Trusted partner


---

# Brightpearl

URL: https://docs.sparklayer.io/help/integrations/erps/brightpearl
Applies to: Shopify

Connect Brightpearl to SparkLayer on Shopify to sync B2B customers and price lists from Brightpearl, and map Brightpearl contact tags to customer groups.

> **Quick summary**
>
> - The Brightpearl integration makes Brightpearl the source of truth for your B2B customers and prices. SparkLayer imports tagged contacts and price lists from Brightpearl into Shopify and SparkLayer.
> - Data syncs one way, from Brightpearl, every 3 hours. Changes made in Shopify don't go back to Brightpearl. Orders reach Brightpearl through your existing Brightpearl–Shopify integration, at your B2B prices.
> - Connect it in the SparkLayer Dashboard at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, under **Multi-channel management**, with your Brightpearl account ID.
> - Needs the Pro or Enterprise plan, a Shopify store and an approved Brightpearl account.

## What it does

[Brightpearl](https://www.brightpearl.com/) is a multi-channel platform for running eCommerce operations, from inventory and stock to order management and fulfilment.

SparkLayer has a direct integration with Brightpearl. You manage your B2B customers and prices in Brightpearl, and SparkLayer brings them into Shopify and SparkLayer, so you don't need to upload them by hand.

How data flows between Brightpearl, SparkLayer and Shopify:

1. **Brightpearl**: Contacts with your SparkLayer tag, and non-cost price lists
2. **SparkLayer**: Imports customers and price lists every 3 hours
3. **Shopify**: Customer records and metafields; B2B prices on the storefront
4. **Brightpearl**: Orders arrive through your existing Brightpearl integration

## What syncs and in which direction

Customers and prices sync one way, from Brightpearl. Orders go back to Brightpearl through your own Brightpearl integration, not through SparkLayer.

| Data | Direction | Details |
| --- | --- | --- |
| Customers | Brightpearl to Shopify and SparkLayer | Brightpearl is the master of your B2B customer data. Changes to tagged contacts sync to Shopify and SparkLayer automatically. |
| Prices | Brightpearl to SparkLayer | Price lists and product prices come from the pricing you set up in Brightpearl. |
| Orders | Shopify to Brightpearl | Orders placed through SparkLayer reach Brightpearl through your **existing** Brightpearl integration, with your B2B prices. |

### Customer data

Customers are matched between Brightpearl and Shopify by the **primary email** in Brightpearl. SparkLayer then syncs this data into Shopify. Some details are stored in Shopify [metafields](https://docs.sparklayer.io/help/glossary.md#metafields): extra fields on the Shopify customer record that SparkLayer reads. The integration fills them in for you.

| Brightpearl | Shopify and SparkLayer |
| --- | --- |
| Address | Customer record in Shopify |
| Receive email newsletters | Customer record in Shopify |
| Primary telephone | Customer record in Shopify |
| First and last name | Customer record in Shopify |
| Title | Shopify metafield (`sparklayer.title`) |
| Company name | Shopify metafield (`sparklayer.company_name`) |
| Customer tag (see [Set up customers in Brightpearl](#set-up-customers-in-brightpearl)) | Shopify metafield (`sparklayer.group`), matched to a customer group |
| Credit limit and balance on account | Shopify metafield (`sparklayer.payment_on_account`), for example `{"credit_limit":1000,"balance":735}` |
| Price list | Shopify metafield |
| Customer custom field `SL_SAGTS` | Shopify metafield, matched to SparkLayer sales agent groups. Must be comma-separated. |

All customer data is managed in Brightpearl. Changes made directly in Shopify don't sync back to Brightpearl.

### Price lists

SparkLayer imports each new non-cost price list automatically and creates a matching price list in **Pricing > Price lists** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/lists)), or **SparkLayer Wholesale > Pricing > Price lists** in the Shopify app:

| Field in SparkLayer | Field in Brightpearl |
| --- | --- |
| Handle / ID | Price list code |
| Name | Price list |
| Currency | Currency |

Prices are matched according to whether the Brightpearl price list is set up as gross or net.

### New customers

New B2B contacts created in Brightpearl are added to Shopify **automatically**, as **Pending** accounts. Shopify sends them an **Activate your account** email so they can set a password.

This email is Shopify's **Customer account invite** notification. You can edit it in **Settings > Notifications** ([open in the Shopify admin](https://admin.shopify.com/settings/notifications/customer)) in the Shopify admin.

## Set up Brightpearl

Check the requirements, connect Brightpearl, then tag your B2B customers and create their price lists in Brightpearl.

### Requirements

- **The Pro or Enterprise plan.** See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
- **A Shopify store** connected to SparkLayer. See [Shopify](https://docs.sparklayer.io/help/platforms/shopify.md).
- **An approved Brightpearl account.** See the [Brightpearl website](http://brightpearl.com/).

### Connect Brightpearl

1. In the SparkLayer Dashboard, go to **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.
2. Under **Multi-channel management**, turn on the switch next to **Brightpearl**.
3. Enter your **Brightpearl account ID**. You'll find it in your Brightpearl admin.
4. Authorise SparkLayer to access your Brightpearl account.

Once you're connected, open Brightpearl at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app to set up the integration. It shows which Brightpearl account you're connected to.

| Setting | What it does |
| --- | --- |
| **Tagged customers to synchronise** | The Brightpearl contact tag whose contacts SparkLayer imports, for example `SparkLayer UK`. See [Set up customers in Brightpearl](#set-up-customers-in-brightpearl). |
| **Tax codes to set as exempt** | Brightpearl tax codes, for example `T0`, for customers who should be tax exempt. |

### Set up customers in Brightpearl

Brightpearl uses **contact tags** to decide which contacts are B2B customers and which [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md) they belong to.

1. In Brightpearl, go to **Settings > Contacts > Tags**.
2. Create a tag for your B2B customers, for example `SparkLayer UK` for a single UK customer group.
3. In SparkLayer, enter the same tag name in **Tagged customers to synchronise** (see [Connect Brightpearl](#connect-brightpearl)) and click **Save**.
4. Add the tag to the Brightpearl contacts you want to import.

You can then set rules for the group, such as minimum orders and price lists, in **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app.

#### Add customer sub-groups

To give some B2B customers different rules, such as a VIP group with special prices, create sub-groups:

1. In Brightpearl, create a tag that starts with your main tag, then a dash and the sub-group name. For example, `SparkLayer UK - VIP`.
2. In SparkLayer, 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 create a customer group named after the part that follows the dash, for example `VIP`.

Contacts with the sub-group tag are then placed in that customer group.

### Set up B2B prices in Brightpearl

1. In Brightpearl, go to **Settings > Products/Inventory > Price lists**.
2. Click **Add new price list** and complete the details. Make sure it isn't a cost price list: only non-cost price lists sync.
3. Open a product in Brightpearl. A tab for each price list now appears on the product's **Prices** tab.
4. Enter the prices, including any price breaks (for example, 1+ at £15.00 and 5+ at £10.00).

SparkLayer imports the new price list automatically. See [Price lists](#price-lists) for how its fields map.

## Limitations

- Shopify doesn't support separate addresses, so the default address in Brightpearl is used as both the shipping and billing address in Shopify.
- If you remove a customer from the customer group, also remove their `b2b` tag from their customer account in Shopify.
- Addresses sync one way, from Brightpearl into Shopify. Don't let customers edit addresses in SparkLayer, or new addresses won't reach Brightpearl.
- Customer sync errors are sent by email. 

## Troubleshooting

**A Brightpearl contact isn't appearing in Shopify**

Check the contact has the tag you entered in **Tagged customers to synchronise**, exactly as written, and has a primary email address. Sync errors are reported by email.

**A customer is in the wrong customer group**

Check the contact's tag. For a sub-group, the part of the tag after the dash must match the name of a customer group in **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app.

**A price list isn't showing in SparkLayer**

Only non-cost price lists sync. Check the price list in Brightpearl isn't set as a cost price list.

**I changed a customer in Shopify and Brightpearl hasn't updated**

Customer data only syncs from Brightpearl to Shopify. Make the change in Brightpearl instead.


---

# Cin7 Core

URL: https://docs.sparklayer.io/help/integrations/erps/cin7-core
Applies to: Shopify

Connect Cin7 Core to SparkLayer on Shopify to sync B2B customers, contacts and sell price tiers, set sync tags and tax-exempt codes, and fix sync issues.

> **Quick summary**
>
> - The Cin7 Core integration makes Cin7 Core the source of truth for your B2B customers and prices. SparkLayer imports tagged customers, their contacts and their price tiers into Shopify and SparkLayer.
> - Data syncs one way, from Cin7 Core, every hour. Orders reach Cin7 Core through your existing Cin7 integration.
> - Connect it in the SparkLayer Dashboard at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, under **Multi-channel management**, with your Cin7 Core account ID and API key.
> - Needs the Pro or Enterprise plan, a Shopify store and an approved Cin7 Core account.

## What it does

[Cin7 Core](https://www.cin7.com/solutions/core/) is an inventory management system for retailers, wholesalers and manufacturers, covering inventory, stock control, order management and fulfilment.

SparkLayer has a direct integration with Cin7 Core. You manage your B2B customers and prices in Cin7 Core, and SparkLayer brings them into Shopify and SparkLayer, with a price list for each price tier.

How data flows between Cin7 Core, SparkLayer and Shopify:

1. **Cin7 Core**: Customers with your sync tags, their contacts, sell price tiers and customer prices
2. **SparkLayer**: Imports them every hour and creates price lists
3. **Shopify**: A customer account per contact, with SparkLayer metafields
4. **Cin7 Core**: Orders arrive through your existing Cin7 integration

Read the [limitations](#known-limitations) before you start.

## What syncs and in which direction

Customers and prices sync one way, from Cin7 Core. Orders go back to Cin7 Core through your own Cin7 integration, not through SparkLayer.

| Data | Direction | Details |
| --- | --- | --- |
| Customers | Cin7 Core to Shopify and SparkLayer | Cin7 Core is the master of your B2B customer data. Changes to customers with your sync tags reach Shopify and SparkLayer automatically. SparkLayer creates a Shopify customer for every contact of each customer it syncs: the customer's **Default** contact becomes the main account, and its other contacts become [company users](https://docs.sparklayer.io/help/customers/company-users.md) under it. |
| Prices | Cin7 Core to SparkLayer | Price lists and product prices come from the pricing you set up in Cin7 Core. |
| Orders | Shopify to Cin7 Core | Orders placed through SparkLayer reach Cin7 Core through your [existing Cin7 integration](https://help.core.cin7.com/hc/en-us/articles/9034589848335-Shopify-Integration), with your B2B prices. |

### Customer data

Customers are matched between Cin7 Core and Shopify by the **contact email** in Cin7 Core. SparkLayer syncs this data into Shopify. Some details are stored in Shopify [metafields](https://docs.sparklayer.io/help/glossary.md#metafields): extra fields on the Shopify customer record that SparkLayer reads. The integration fills them in for you.

| Cin7 Core | Shopify and SparkLayer |
| --- | --- |
| First and last name | Customer record in Shopify |
| Email and phone number | Customer record in Shopify |
| Addresses | Customer record in Shopify |
| Tax rule (using **Tax-Exempt Codes**) | Tax exemption on the customer record in Shopify |
| Tags | SparkLayer customer group, in a Shopify metafield called "Group". Only **Additional Customer Tags** appear as tags on the Shopify customer. |
| Company name | Shopify metafield called "Company" |
| Discount | Shopify metafield called "Discount Percentage" |
| Credit limit and on hold | Shopify metafield called "Payment On Account" |
| Sale price tier and customer-specific prices | Shopify metafield, so the customer sees the right prices (see [Price lists](#price-lists)) |

All customer data is managed in Cin7 Core. Changes made directly in Shopify don't sync back, and are overwritten at the next sync.

### Price lists

SparkLayer creates several kinds of price list from your Cin7 Core prices. They appear in **Pricing > Price lists** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/lists)), or **SparkLayer Wholesale > Pricing > Price lists** in the Shopify app as **Integration** price lists.

| Price list | When it's created |
| --- | --- |
| Sell price tier | One for each sell price tier you use. |
| Customer-specific | One for each customer with prices on their **Product prices** tab. |
| Alternative currency | When a customer uses a currency other than your base currency. For example, if your store is in GBP and you assign a customer USD, SparkLayer creates a USD copy of the tier ("Dear Tier Price 1 USD"), converting the GBP prices at the live exchange rate. |
| Prefixed | Generic price lists applied to every customer, so a basic sell price tier is always in place even if the customer's Cin7 Core setup doesn't assign one. |

When a customer views a product, SparkLayer checks their Cin7 Core price lists in this order and uses the first price it finds:

1. The customer-specific price list, if there is one.
2. The customer's sell price tier.

Customers with other currencies or discounts get extra price lists. As with any price lists, the first one with the product's SKU wins: see [Price list order](https://docs.sparklayer.io/help/pricing/managing-pricing.md#price-list-order).

**Where the price list order is stored, for your developer**

Each customer's price lists are listed in order in a Shopify customer metafield called **Price List - Cin7**, for example `["dear-cust-…", "dear-tier-1-eur"]`. See [Metafields](https://docs.sparklayer.io/developers/data/metafields.md) for how the price list metafield works.

### Invite new customers

New customers created in Cin7 Core are added to Shopify **automatically**, as **Pending** accounts. If **Send customers an invite email when activated in Cin7 Core** is ticked, Shopify sends them an **Activate your account** email so they can set a password.

This email is Shopify's **Customer account invite** notification. You can edit it in **Settings > Notifications** ([open in the Shopify admin](https://admin.shopify.com/settings/notifications/customer)) in the Shopify admin. To stop sending it, untick the setting in **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app (click **Modify** next to Cin7 Core).

## Set up Cin7 Core

Check the requirements, connect Cin7 Core, then set up your customers and price tiers in Cin7 Core.

### Requirements

- **The Pro or Enterprise plan.** See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
- **A Shopify store** connected to SparkLayer. See [Shopify](https://docs.sparklayer.io/help/platforms/shopify.md).
- **An approved Cin7 Core account.** See the [Cin7 website](https://www.cin7.com/solutions/core/).

### Connect Cin7 Core

1. In **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app, create the [customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md) you want to use. To test, start with a new group and a dummy customer.
2. In the SparkLayer Dashboard, go to **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.
3. Under **Multi-channel management**, turn on the switch next to **Cin7 Core**.
4. Fill in the settings below, then click **Save**.

To change the settings later, open Cin7 Core at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.

| Setting | What it does |
| --- | --- |
| **Account ID** | The unique identifier for your Cin7 Core account. You'll find it in Cin7 Core under **Integration > API**. |
| **API Key** | Your Cin7 Core API key: a code from Cin7 Core that lets SparkLayer read your data. Find it under **Integration > API**. It isn't shown again after saving. |
| **Customer Sync Tags** | Only Cin7 Core customers with one of these tags are imported to Shopify. Each tag must match a SparkLayer customer group exactly. Separate tags with a comma and no spaces, for example `base,gold`. |
| **Additional Customer Tags** | If an imported customer has any of these tags in Cin7 Core, they get the same tags in Shopify, prefixed with `spark-`. They must be valid Shopify tags and mustn't clash with your SparkLayer customer groups. Shopify only: ignored on other platforms. |
| **Tax-Exempt Codes** | Cin7 Core tax rules that should make a customer tax exempt in Shopify, for example `TAXFREE`. |
| **Send customers an invite email when activated in Cin7 Core** | Sends new customers Shopify's account invite email, asking them to confirm their account. See [Invite new customers](#invite-new-customers). |
| **Ignore Non-Default Contacts** | When ticked, only each customer's **Default** contact syncs to SparkLayer. |

### Set up customers in Cin7 Core

1. In Cin7 Core, go to **Sale > Customer** and open or create the customer.
2. On the **General** tab, fill in:
   - **Name** (first and last name are required)
   - **Currency**
   - **Sale price tier**
   - **Tax rule**. To make the customer tax exempt in Shopify, choose a rule you've listed in **Tax-Exempt Codes**.
   - **Tags**: add the tag for the customer's SparkLayer customer group, for example `base` or `gold`.
3. On the **Addresses** tab, add a full address.
4. On the **Contacts** tab, add each contact with a first and last name and a valid email address. Tick **Default** for the main contact.
5. Check the tag is listed in **Customer Sync Tags** in SparkLayer.

The customer is imported at the next sync. You don't need to tag the customer with the customer group in Shopify: SparkLayer adds the group as a metafield. If a customer has several contacts, the **Default** contact becomes the main account and the others become company users under it.

### Set up B2B prices in Cin7 Core

Cin7 Core has **up to 10 price tiers**, so you can give different customer levels different prices. You can also set customer-specific prices on top.

1. To rename the tiers, go to **Settings > General Settings > Sell Price Tier Names** in Cin7 Core. SparkLayer doesn't use the custom names: tiers always appear in SparkLayer as "Sell Price Tier 1" to "Sell Price Tier 10".
2. Open a product and go to the **Prices** tab. Enter the price for each tier you use.
3. Open the customer and choose their **Sale price tier** on the **General** tab. This is the price list they see when they sign in.

#### Set customer-specific prices

1. In Cin7 Core, open the customer and go to **Product prices**.
2. Search for a product and enter a fixed **Custom price**.

SparkLayer creates a customer-specific price list for these prices in **Pricing > Price lists** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/lists)), or **SparkLayer Wholesale > Pricing > Price lists** in the Shopify app.

## Limitations

- SparkLayer uses the internal sell price tier names, not the custom names you can set in Cin7 Core settings.
- Changing a customer's email address creates another customer in Shopify. Disable the old account manually.
- If you change a customer's **Default** contact in Cin7 Core, manually disable the Shopify account for the old default contact.
- Removing the tag from a customer doesn't disable them in Shopify.
- Shopify doesn't support separate addresses, so the default address in Cin7 Core is used as both the shipping and billing address in Shopify.
- Addresses sync one way, from Cin7 Core into Shopify. Don't let customers edit addresses in SparkLayer: new addresses won't reach Cin7 Core and are replaced at the next sync.

## Troubleshooting

**My customers aren't appearing in Shopify**

Check that:

- **The customer has the right tag** in Cin7 Core, matching a SparkLayer customer group name, and the tag is in **Customer Sync Tags**.
- **The tag format is right**: tags separated by commas with no spaces, for example `base,gold`.
- **The customer has a Default contact** with a valid email address.

**Customer account invites aren't being sent**

Shopify sends the **Customer account invite** email when a new customer is created. Check **Send customers an invite email when activated in Cin7 Core** is ticked in the Cin7 Core settings in **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.

**Customer-specific prices aren't showing**

- After changing prices, wait for the next sync to finish. Syncs run every hour.
- Check the Shopify customer has the **Price List - Cin7** metafield with the right price lists.

**Changes made in Shopify aren't reflected in Cin7 Core**

The integration is one way, from Cin7 Core to Shopify, so always make changes in Cin7 Core. Changes made directly in Shopify are overwritten at the next sync.

**Product prices look wrong for a customer**

Check that:

- **The customer's price tier** (**Sale price tier**) or customer-specific prices are right in Cin7 Core.
- **The tier prices** in Cin7 Core have the values you expect for those products.
- **No old price lists or tags** are still linked to the customer in SparkLayer.

**Duplicate customers appear in Shopify**

Changing a customer's email address, or their **Default** contact, in Cin7 Core creates a new Shopify customer. Disable the old account manually.


---

# Katana

URL: https://docs.sparklayer.io/help/integrations/erps/katana
Applies to: Shopify

Connect Katana to SparkLayer on Shopify to sync B2B customers and price lists, map customer categories to customer groups, and fix common sync issues.

> **Quick summary**
>
> - The Katana integration makes Katana the source of truth for your B2B customers and prices. SparkLayer imports customers and price lists from Katana into Shopify and SparkLayer.
> - Data syncs one way, from Katana, every 4 hours. Changes made in Shopify don't go back to Katana. A customer's **Category** in Katana decides their SparkLayer customer group.
> - Connect it in the SparkLayer Dashboard at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, under **Multi-channel management**, by signing in to Katana.
> - Needs the Pro or Enterprise plan, a Shopify store and an approved Katana account.

## What it does

[Katana](https://katanamrp.com/) is a manufacturing ERP that gives you a live view of sales, inventory and production.

SparkLayer has a direct integration with Katana. You manage your B2B customers and price lists in Katana, and SparkLayer brings them into Shopify and SparkLayer.

How data flows between Katana, SparkLayer and Shopify:

1. **Katana**: Customers with a category, and price lists
2. **SparkLayer**: Imports customers and price lists every 4 hours
3. **Shopify**: Customer records and metafields; B2B prices on the storefront

## What syncs and in which direction

Customers and prices sync one way, from Katana. SparkLayer's Katana integration doesn't send orders to Katana.

| Data | Direction | Details |
| --- | --- | --- |
| Customers | Katana to Shopify and SparkLayer | Katana is the master of your B2B customer data. Changes to customer records sync to Shopify and SparkLayer automatically. |
| Prices | Katana to SparkLayer | Price lists and product prices come from the price lists you set up in Katana. |

### Customer data

Customers are matched between Katana and Shopify by the **primary email** in Katana. SparkLayer then syncs this data into Shopify. Some details are stored in Shopify [metafields](https://docs.sparklayer.io/help/glossary.md#metafields): extra fields on the Shopify customer record that SparkLayer reads. The integration fills them in for you.

| Katana | Shopify and SparkLayer |
| --- | --- |
| Address | Customer record in Shopify |
| Primary telephone | Customer record in Shopify |
| First and last name | Customer record in Shopify |
| Customer category | Customer record in Shopify, matched to a customer group |
| Company name | Shopify metafield |
| Discount rate | Shopify metafield |
| Price list | Shopify metafield |

### Price lists

SparkLayer imports each new price list automatically and creates a matching price list in **Pricing > Price lists** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/lists)), or **SparkLayer Wholesale > Pricing > Price lists** in the Shopify app:

| Field in SparkLayer | Field in Katana |
| --- | --- |
| Handle / ID | Price list ID |
| Name | Price list name |
| Currency | Currency |

Price lists use Katana's base currency. If you give a customer a different currency in Katana, SparkLayer creates an automatic price list with currency conversion for them.

### New customers

New customers created in Katana are added to Shopify as **Pending** accounts. If **Send customers an invite email when activated in Katana** is ticked, Shopify sends them an **Activate your account** email so they can set a password.

This email is Shopify's **Customer account invite** notification. You can edit it in **Settings > Notifications** ([open in the Shopify admin](https://admin.shopify.com/settings/notifications/customer)) in the Shopify admin.

## Set up Katana

Check the requirements, connect Katana, then set up your customers and price lists in Katana.

### Requirements

- **The Pro or Enterprise plan.** See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
- **A Shopify store** connected to SparkLayer. See [Shopify](https://docs.sparklayer.io/help/platforms/shopify.md).
- **An approved Katana account.** See the [Katana website](http://katanamrp.com/).

### Connect Katana

1. In the SparkLayer Dashboard, go to **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.
2. Under **Multi-channel management**, turn on the switch next to **Katana**.
3. Authorise SparkLayer to access your Katana account.

To change the settings later, open Katana at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.

| Setting | What it does |
| --- | --- |
| **Send customers an invite email when activated in Katana** | Sends new customers Shopify's account invite email, asking them to confirm their account. See [New customers](#new-customers). |

### Set up customers in Katana

Katana uses the customer's **Category** to decide which [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md) they belong to in SparkLayer.

1. In SparkLayer, 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 note the tag of the group you want, for example `b2b-ca` for a group called **B2B - Canada**.
2. In Katana, create or open the customer and set their **Category** to that tag, for example `b2b-ca`.
3. Check the customer has a primary email address. It's used to match them in Shopify.

You can then set rules for the group, such as minimum orders and price lists, in **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app.

### Set up B2B prices in Katana

1. In Katana, go to **Price lists** and click **+ Price list**.
2. Enter a **Price list name**, for example `UKVIP`.
3. On the **Product pricing** tab, add products and set their prices. For each product, choose an **Adjustment method** (for example **Fixed**) and an **Amount**. Katana shows the **Final price**.
4. On the **Customers** tab, assign the price list to customers. 

SparkLayer imports the new price list automatically. See [Price lists](#price-lists) for how its fields map.

## Limitations

- SparkLayer doesn't send B2B orders to Katana. The integration only brings customers and prices in from Katana.
- Shopify doesn't support separate addresses, so the default address in Katana is used as both the shipping and billing address in Shopify.
- If you remove a customer from the customer group, also remove their `b2b` tag from their customer account in Shopify.
- Addresses sync one way, from Katana into Shopify. Don't let customers edit addresses in SparkLayer, or new addresses won't reach Katana.
- Prices you delete in Katana aren't removed from SparkLayer. Delete them manually in **Pricing > Price lists** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/lists)), or **SparkLayer Wholesale > Pricing > Price lists** in the Shopify app.

## Troubleshooting

**Why isn't my customer data syncing from Katana to Shopify?**

Check that:

- **The customer has a primary email address** in Katana. It's used to match them.
- **The Katana integration is turned on and authorised** in **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.

**Why aren't customer addresses updating in Katana when edited in SparkLayer?**

Addresses sync one way, from Katana to Shopify, so changes made in SparkLayer don't reach Katana. To keep data consistent, turn off address editing in SparkLayer.

**New customers in Katana aren't appearing in Shopify. What should I check?**

Check that:

- **The Katana integration is turned on and authorised.**
- **New customers have all the required fields**, especially the email address.
- **The invite email settings are right**: **Send customers an invite email when activated in Katana**, and Shopify's **Customer account invite** email.

**My price list changes in Katana aren't showing in SparkLayer. What might be wrong?**

- Create and update price lists in Katana, not in SparkLayer.
- Prices deleted in Katana don't sync. Remove old prices manually in SparkLayer.

**Why is the wrong price showing for a B2B customer?**

Check that:

- **The customer is assigned to the right price list** in Katana.
- **The right currency is set on the customer**, if they use a different currency from your base currency.

**My new price list isn't appearing in SparkLayer. What should I do?**

Check the price list is saved in Katana, then allow time for SparkLayer to import it.

**Where can I change the invite email that new customers receive?**

In the Shopify admin, go to **Settings > Notifications** ([open in the Shopify admin](https://admin.shopify.com/settings/notifications/customer)) and edit the **Customer account invite** template. SparkLayer uses it when activating new accounts created from Katana.


---

# Linnworks

URL: https://docs.sparklayer.io/help/integrations/erps/linnworks

Connect Linnworks to SparkLayer to sync B2B prices, price breaks and units of measure from extended properties, and route wholesale orders into Linnworks.

> **Quick summary**
>
> - The Linnworks integration makes Linnworks the source of truth for your B2B prices. You enter them as **extended properties** (custom fields) on each Linnworks inventory item.
> - Prices sync one way, from Linnworks, every hour. Customers stay on your eCommerce platform, and orders reach Linnworks through your existing Linnworks integration.
> - Connect it in the SparkLayer Dashboard at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, under **Multi-channel management**, with a token from the SparkLayer app in Linnworks.
> - Needs the Pro or Enterprise plan and an approved Linnworks account. It works with every eCommerce platform.

## What it does

[Linnworks](https://www.linnworks.com/) is a multi-channel platform for running eCommerce operations, from inventory and stock to order management and fulfilment.

SparkLayer has a direct integration with Linnworks. You keep your B2B prices, including price breaks and units of measure, on your Linnworks inventory items, and SparkLayer adds them to your price lists.

How data flows between Linnworks, SparkLayer and your store:

1. **Linnworks**: B2B prices in extended properties named b2b-…
2. **SparkLayer**: Imports prices into your price lists every hour
3. **Your store**: Signed-in B2B customers see their prices
4. **Linnworks**: Orders arrive through your existing Linnworks integration

## What syncs and in which direction

Only prices sync, one way, from Linnworks into SparkLayer **every hour**. Orders go to Linnworks through your own Linnworks integration, not through SparkLayer.

| Data | Direction | Details |
| --- | --- | --- |
| Prices | Linnworks to SparkLayer | Product prices come from **extended properties** on Linnworks inventory items. |
| Orders | SparkLayer to your store to Linnworks | Orders placed through SparkLayer reach Linnworks through your **existing** Linnworks integration, with your B2B prices. |
| Customers | Not synced | You manage customers on your eCommerce platform as usual. |

To check the prices SparkLayer has received for a product, use **Product data lookup** at **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app. See [Look up a product's data](https://docs.sparklayer.io/help/integrations/data-sync.md#look-up-a-products-data).

## Set up Linnworks

Check the requirements and connect Linnworks. Then create your price lists in SparkLayer, add their prices in Linnworks and assign them to customers.

### Requirements

- **The Pro or Enterprise plan.** See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
- **Any eCommerce platform** connected to SparkLayer. 
- **An approved Linnworks account.** See the [Linnworks website](https://www.linnworks.com/).

### Connect Linnworks

1. Sign in to your Linnworks account.
2. [Open the SparkLayer app authorisation page](https://apps.linnworks.net/Authorization/Authorize/d4d9f57c-ea0e-4ecf-8c6d-eaa5632d4581) to install the SparkLayer app. You're given an **authorisation token**.
3. In the SparkLayer Dashboard, go to **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.
4. Under **Multi-channel management**, turn on the switch next to **Linnworks**.
5. Paste the authorisation token into **Token** and click **Save**.

### Create price lists in SparkLayer

With Linnworks, you create the price lists in SparkLayer first, then add prices to them from Linnworks. Price lists decide which prices each customer sees when they sign in.

1. In the Dashboard, 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.
2. Click **Create Price List**.
3. Enter a **Handle** (a short, unique ID you'll use in Linnworks) and a **Name**, then save. 
4. Repeat for each price list you need.

Make a note of each handle: you'll use it in Linnworks.

### Add B2B prices in Linnworks

You add B2B prices with Linnworks' **extended properties** feature. See Linnworks' guide to [extended properties](https://assets.linnworks.com/support/inventory/my-inventory/edit-inventory-item/extended-properties/).

1. In Linnworks, open a product and go to the **Extended properties** tab.
2. Click **Add New**.
3. Fill in the **Name**, **Value** and **Type** as shown below.
4. Repeat for each price list the product belongs to.

| Field | What to enter |
| --- | --- |
| **Name** | `b2b-` followed by the price list's handle in SparkLayer. For example, for the handle `base-list`, enter `b2b-base-list`. |
| **Value** | The prices, separated by commas (see below). |
| **Type** | `Other` |

#### Format the price value

Separate prices with commas. The first price is always the price for one item.

| To set | How to write it | Example |
| --- | --- | --- |
| A single price | The price for one item. | `7.00` |
| Price breaks (tiered pricing) | Add each tier as the quantity, a plus sign and the price. | £7.00 for one item and £5.00 for 10 or more: `7.00,10+5.00` |
| Units of measure | Add a plus sign and a unit key after a tier. See [unit of measure pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md). | 10 items make a box at £5.00 each and 100 make a crate at £4.00 each: `7.00,10+5.00+box,100+4.00+crate` |

For example, a product on 2 price lists could have these extended properties:

| Name | Value | Type |
| --- | --- | --- |
| `b2b-base-list` | `10,5+7.50` | Other |
| `b2b-uk-vip` | `7.50,10+5.75,50+5` | Other |

#### Update prices in bulk

To change many prices at once, use Linnworks' bulk import tools. See Linnworks' guide to [importing and exporting data](https://assets.linnworks.com/support/settings/import-and-export-data/).

### Assign prices to customers

Customers see the Linnworks prices once their [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md) uses the right price list. Set this up in **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app.

To test it, sign in to your store as a B2B customer and open a product. You should see the price you set in Linnworks.

## Limitations

- Customers don't sync. You manage them on your eCommerce platform.
- Orders don't go through SparkLayer. They reach Linnworks through your existing Linnworks integration.
- Price changes take up to an hour to reach SparkLayer, because prices sync every hour.

## Troubleshooting

**Prices from Linnworks aren't showing**

Check that:

- **The extended property Name** is `b2b-` plus the exact price list handle in SparkLayer.
- **The Type** is `Other`.
- **An hour has passed** since the change. Prices sync every hour.
- **The customer's group uses that price list** in **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app.

**Price breaks aren't working**

Check the value format: the single-item price first, then each tier as quantity, plus sign and price, separated by commas, for example `7.00,10+5.00`.


---

# Unleashed

URL: https://docs.sparklayer.io/help/integrations/erps/unleashed
Applies to: Shopify

Connect Unleashed to SparkLayer on Shopify to sync customers by customer type, with sell price tiers, customer pricing and discounts, and fix sync issues.

> **Quick summary**
>
> - The Unleashed integration makes Unleashed the source of truth for your B2B customers and prices. SparkLayer imports customers of the customer types you choose, with their sell price tiers, customer pricing and discounts.
> - Data syncs one way, from Unleashed, every 4 hours. Orders reach Unleashed through your existing Unleashed integration.
> - Connect it in the SparkLayer Dashboard at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, under **Multi-channel management**, with your Unleashed API ID and API key.
> - Needs the Pro or Enterprise plan, a Shopify store and an approved Unleashed account. 2 settings in your Unleashed–Shopify integration must change first.

## What it does

[Unleashed](https://www.unleashedsoftware.com/) is an inventory management system for manufacturers, wholesalers and distributors, covering inventory, stock, order management and fulfilment.

SparkLayer has a direct integration with Unleashed. You manage your B2B customers and prices in Unleashed, and SparkLayer brings them into Shopify and SparkLayer, with a price list for each price tier, customer price and discount.

How data flows between Unleashed, SparkLayer and Shopify:

1. **Unleashed**: Customers of your chosen customer types, sell price tiers and customer pricing
2. **SparkLayer**: Imports them every 4 hours and creates price lists
3. **Shopify**: Customer records and metafields; B2B prices on the storefront
4. **Unleashed**: Orders arrive through your existing Unleashed integration

Before you start, check the [requirements](#requirements): 2 settings in your Unleashed–Shopify integration need to change. Read the [limitations](#known-limitations) too.

## What syncs and in which direction

Customers and prices sync one way, from Unleashed. Orders go back to Unleashed through your own Unleashed integration, not through SparkLayer.

| Data | Direction | Details |
| --- | --- | --- |
| Customers | Unleashed to Shopify and SparkLayer | Unleashed is the master of your B2B customer data. Changes to customers with one of your chosen customer types reach Shopify and SparkLayer automatically. |
| Prices | Unleashed to SparkLayer | Price lists and product prices come from the pricing you set up in Unleashed. |
| Orders | Shopify to Unleashed | Orders placed through SparkLayer reach Unleashed through your **existing** [Unleashed integration](https://support.unleashedsoftware.com/hc/en-us/articles/4402425783577-Shopify-Integration-Introduction), with your B2B prices. |

### Customer data

Customers are matched between Unleashed and Shopify by the **primary contact email** in Unleashed. SparkLayer syncs this data into Shopify, where you can see it on the customer record. Some details are stored in Shopify [metafields](https://docs.sparklayer.io/help/glossary.md#metafields): extra fields on the Shopify customer record that SparkLayer reads. The integration fills them in for you.

| Unleashed | Shopify and SparkLayer |
| --- | --- |
| Address | Customer record in Shopify |
| Phone | Customer record in Shopify |
| First and last name | Customer record in Shopify |
| Company name | Shopify metafield |
| Stop Credit | Shopify metafield, used to allow payment on account |
| Taxable | Customer record in Shopify |

All customer data is managed in Unleashed. Changes made directly in Shopify don't sync back to Unleashed.

### Price lists

SparkLayer creates several kinds of price list from your Unleashed prices. They appear in **Pricing > Price lists** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/lists)), or **SparkLayer Wholesale > Pricing > Price lists** in the Shopify app as **Integration** price lists.

| Price list | When it's created |
| --- | --- |
| Default | Always. Holds every product's **Default Sell Price** from the product's **Sale** tab, as the baseline price. |
| Sell price tier | One for each sell price tier you use. |
| Customer-specific | One for each customer with prices on their **Customer Pricing** tab. |
| Discounted | When a customer has a **Discount (%)**, for example 10% off all products. |
| Alternative currency | When a customer uses a currency other than your base currency. |
| Prefixed | Generic price lists applied to every customer, so a basic sell price tier is always in place even if the customer's Unleashed setup doesn't assign one. |

When a customer views a product, SparkLayer checks their Unleashed price lists in this order and uses the first price it finds:

1. The customer's product-specific prices from **Customer Pricing**.
2. Their percentage discount on top of their price tier.
3. Their sell price tier.
4. The **Default Sell Price**, as a fallback.

Customers with other currencies or discounts get extra price lists. As with any price lists, the first one with the product's SKU wins: see [Price list order](https://docs.sparklayer.io/help/pricing/managing-pricing.md#price-list-order).

**Where the price list order is stored, for your developer**

Each customer's price lists are listed in order in a Shopify customer metafield called **Price List - Unleashed**, for example `["Customer-Test001", "SellPriceTier3-30", "SellPriceTier3", "DefaultSellPrice"]`. See [Metafields](https://docs.sparklayer.io/developers/data/metafields.md) for how the price list metafield works.

### Invite new customers

New customers created in Unleashed are added to Shopify **automatically**, as **Pending** accounts. If **Send customers an invite email when activated in Unleashed** is ticked, Shopify sends them an **Activate your account** email so they can set a password.

This email is Shopify's **Customer account invite** notification. You can edit it in **Settings > Notifications** ([open in the Shopify admin](https://admin.shopify.com/settings/notifications/customer)) in the Shopify admin. To stop sending it, untick the setting in **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app (click **Modify** next to Unleashed).

## Set up Unleashed

Check the requirements, connect Unleashed, then set up your customers and prices in Unleashed.

### Requirements

- **The Pro or Enterprise plan.** See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
- **A Shopify store** connected to SparkLayer. See [Shopify](https://docs.sparklayer.io/help/platforms/shopify.md).
- **An approved Unleashed account.** See the [Unleashed website](https://www.unleashedsoftware.com/).
- **Customer synchronisation turned off** in your Unleashed–Shopify integration, so SparkLayer is the only thing creating B2B customers in Shopify.
- **Order Import Options not set to import orders to a single customer**, in your Unleashed order configuration. If you need that, use a second store for B2B.

### Connect Unleashed

1. In Unleashed, go to **Settings > System > Customer Types**. Add a customer type for each group of customers you'll give different prices, for example `Base` and `Gold`.
2. In SparkLayer, 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 create a [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md) for each customer type, with a name that matches exactly. To test, start with a new group and a dummy customer before you use an existing group.
3. In the SparkLayer Dashboard, go to **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.
4. Under **Multi-channel management**, turn on the switch next to **Unleashed**.
5. Fill in the settings below, then click **Save**.

To change the settings later, open Unleashed at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.

| Setting | What it does |
| --- | --- |
| **API ID** | The unique identifier for your Unleashed account. You'll find it in Unleashed under **Integration > Unleashed API Access**. |
| **API Key** | Your Unleashed API key: a code from Unleashed that lets SparkLayer read your data. Find it under **Integration > Unleashed API Access**. It isn't shown again after saving. |
| **Customer Types** | The Unleashed customer types to sync to Shopify. Each must match a customer type in Unleashed exactly. Separate them with a comma and no spaces, for example `Base,Gold`. |
| **Price Lists** | Unleashed price lists to give the highest priority for every customer, above any other price list assigned to them. Useful for promotions (see [Run a promotion](#run-a-promotion-with-a-priority-price-list)). Separate them with a comma and no spaces, for example `SellPriceTier1,SellPriceTier2`. Leave blank if you don't need one. |
| **Send customers an invite email when activated in Unleashed** | Sends new customers Shopify's account invite email, asking them to confirm their account. See [Invite new customers](#invite-new-customers). |
| **Configure Sell Price Tier currency codes** | For multi-currency stores. When ticked, a **Currency Code** field appears for each of the 10 tiers (for example `USD`). Leave a tier blank to use your store's default currency. See [Price in more than one currency](#price-in-more-than-one-currency). |

### Set up customers in Unleashed

1. In Unleashed, go to **Customers > Add Customer**, or open an existing customer.
2. On the **Details** tab, choose a **Customer Type** that's listed in the SparkLayer **Customer Types** setting. This decides the customer's SparkLayer customer group.
3. Set any tax settings, such as **Taxable**.
4. On the **Address** tab, add a full address.
5. Check the customer has a valid email address on their primary contact. Customers without one can't sync.

The customer is imported at the next sync and tagged with their customer group in the usual SparkLayer way.

### Set up B2B prices in Unleashed

Unleashed has **up to 10 sell price tiers**, so you can give different customer levels different prices. You can also set customer-specific prices and discounts on top.

1. To rename the tiers, go to **Settings > System > Sell Price Tiers** in Unleashed. SparkLayer doesn't use the custom names: tiers always appear in SparkLayer as "Sell Price Tier 1" to "Sell Price Tier 10".
2. Open a product (**Inventory > Products > View Products**) and go to the **Sale** tab. Under **Sell Price Tiers**, enter the price for each tier you use. The **Default Sell Price** is the base price for every customer.
3. Open the customer and choose their **Sell Price Tier** on the **Details** tab. This is the price list they see when they sign in.

#### Set customer-specific prices

1. In Unleashed, open the customer and go to the **Customer Pricing** tab.
2. Search for a **Product** and enter a **Price / Discount %**.
3. Choose a **Price Type**: **Fixed price** or **Discount %**.
4. For a discount, choose what it's taken from in **Discount From**: **Default Sell Price** or **Customer Price Tier**. See the [limitations](#known-limitations) for how Discount % works.
5. Click **Add**.

SparkLayer creates a customer-specific price list for these prices in **Pricing > Price lists** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/lists)), or **SparkLayer Wholesale > Pricing > Price lists** in the Shopify app.

#### Give a customer an extra discount

To give a customer a percentage off on top of their price tier, open the customer in Unleashed and enter it in **Discount (%)** on the **Details** tab. SparkLayer creates a discounted price list for them.

#### Run a promotion with a priority price list

To run a promotion for all customers, adjust the product prices in one of your sell price tiers. Then enter that tier in the **Price Lists** setting in SparkLayer. It now takes priority over every customer's other price lists.

#### Price in more than one currency

If you sell in more than one currency, use a sell price tier for each currency. For example, Sell Price Tier 1 for GBP and Sell Price Tier 2 for EUR.

1. In **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, open Unleashed.
2. Tick **Configure Sell Price Tier currency codes**.
3. Enter the currency code for each tier you use, for example `EUR` in **Tier 2 Currency Code**, and click **Save**.

If you only sell in your store's base currency, you don't need to do this.

## Limitations

- **Discount % in Customer Pricing.** Because of a limitation in the Unleashed API, a **Customer Pricing** line with the **Discount %** price type only affects the customer's **Sell Price Tier**, not the **Default Sell Price** or the **Customer Price Tier**. 
- SparkLayer uses the internal sell price tier names, not the custom names you can set in Unleashed settings.
- Customers marked **Obsolete** in Unleashed don't sync. If you make a customer obsolete, disable them manually in Shopify.
- Changing a customer's email address creates another customer in Shopify. Disable the old account manually.
- Only the primary contact syncs. If you choose a new primary contact, manually disable the existing Shopify customer.
- Your Unleashed–Shopify integration needs customer synchronisation turned off, and mustn't import orders to a single customer. See [Requirements](#requirements).

## Troubleshooting

**Why are some of my customers not syncing from Unleashed to Shopify?**

Check the customer's **Customer Type** in Unleashed matches one in the SparkLayer **Customer Types** setting exactly, and that the names there are separated by commas with no spaces (for example `Base,Gold`). Also check the customer's email address in Unleashed: it's used to match the records.

**Why am I not seeing B2B price updates in my Shopify store?**

Check the price lists in Unleashed are assigned to the right customers. If you use the **Price Lists** setting, check the names match and are separated by commas with no spaces.

**Why don't changes I make in Shopify show in Unleashed?**

Unleashed is the single source of truth for customers in this integration, so changes made in Shopify don't sync back. Make the change in Unleashed and the integration pushes it to Shopify.

**What should I do if Shopify orders aren't appearing in Unleashed?**

Check the integration settings, especially the **API Key** and **Customer Types**. If they're right, look for sync errors in the order logs in SparkLayer.

**Why aren't my custom-named price tiers showing in SparkLayer?**

SparkLayer uses Unleashed's default sell price tier names, such as "Sell Price Tier 1". Custom names don't appear in SparkLayer.

**Why do I have duplicate customers in Shopify after changing an email in Unleashed?**

Changing a customer's email address in Unleashed creates a new customer in Shopify. Disable the old account in Shopify after making the change.

**Why aren't customer-specific discounts applied correctly?**

Check the **Discount %** is set correctly in Unleashed. A **Discount %** line only affects the sell price tier, not the **Default Sell Price**. For other discounts, apply them to the relevant price tiers or use fixed prices in **Customer Pricing**.


---

# Accountancy

URL: https://docs.sparklayer.io/help/integrations/accountancy
Applies to: Shopify

Connect SparkLayer to Xero or QuickBooks Online so B2B orders become invoices automatically and customers can download them from their account.

> **Quick summary**
>
> - SparkLayer has direct integrations with **Xero** and **QuickBooks Online**. They turn B2B orders paid by invoice or on account into invoices in your accounting app, and can create the matching contacts.
> - Data goes from SparkLayer into your accounting app, shortly after each eligible B2B order comes in. Each guide lists which orders qualify. With Xero, payments on those invoices also come back to SparkLayer. Changes you make to an invoice in the accounting app don't come back.
> - Connect one in the SparkLayer Dashboard at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, under **Accountancy**: turn on its switch and sign in to Xero or QuickBooks. Both need the Pro or Enterprise plan and a Shopify store.
> - Customers can view and download each invoice from **My Account** on your store.

## How the accountancy integrations work

How a B2B order becomes an invoice:

1. **B2B order**: Paid by invoice or on account
2. **SparkLayer**: Matches or creates the contact
3. **Xero or QuickBooks**: Invoice created through the API
4. **My Account**: Customer views and downloads the invoice

Both integrations work the same way, with a few differences:

| Feature | Xero | QuickBooks Online |
| --- | --- | --- |
| Creates invoices for Pay by Invoice and Pay on Account orders | Yes | Yes |
| Creates contacts automatically (optional) | Yes | Yes |
| Invoice per shipment for Pay on Account orders (optional) | Yes | Yes |
| Sales receipts for upfront payment orders | Not documented | Yes (optional) |
| Payments on invoices shown on the SparkLayer order | Yes | Not documented |

To see where each integration fits in the Pay by Invoice and Pay on Account flows, try the interactive guide [How payments work](https://docs.sparklayer.io/help/guides/how-payments-work.md).

- [Xero](https://docs.sparklayer.io/help/integrations/accountancy/xero.md): Create invoices and import payments · Direct integration
- [QuickBooks Online](https://docs.sparklayer.io/help/integrations/accountancy/quickbooks.md): Create invoices from B2B orders · Direct integration


---

# QuickBooks Online

URL: https://docs.sparklayer.io/help/integrations/accountancy/quickbooks
Applies to: Shopify

Connect QuickBooks Online to SparkLayer on Shopify to create invoices, sales receipts and customers from B2B orders, and set tax codes and income accounts.

> **Quick summary**
>
> - The QuickBooks Online integration creates an invoice in QuickBooks for each B2B order paid by invoice or on account. It can create the QuickBooks customer too.
> - Invoices are created shortly after the order reaches **processing** (or, if you choose, as each shipment is fulfilled). Data goes one way: changes you make to an invoice in QuickBooks don't come back to SparkLayer.
> - Connect it in the SparkLayer Dashboard at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, under **Accountancy**: turn on the switch and sign in to QuickBooks. Needs the Pro or Enterprise plan, a Shopify store and QuickBooks **Online** (not the desktop version).
> - Customers can view and download their invoices from **My Account** on your store.

## What it does

[QuickBooks Online](https://quickbooks.intuit.com/) is online accounting software for managing finances, invoices, inventory and customer records.

SparkLayer has a direct integration with QuickBooks Online. Your B2B orders sync to QuickBooks as invoices and contacts, so there's less manual data entry and no need for another app to keep the systems in sync.

How a B2B order becomes a QuickBooks invoice:

1. **B2B order**: Paid by invoice or on account, and processing or shipped
2. **Contact**: Matched by account number or email, or created
3. **QuickBooks invoice**: Created in the background through the API
4. **My Account**: View & Download Invoice button on the order

### Let customers view invoices

When an invoice is ready, a **View & Download Invoice** button appears on the order in **My Account** on your store. It opens the public invoice page generated by QuickBooks. If the button doesn't appear, see [Troubleshooting](#troubleshooting).

## What syncs and in which direction

Data goes one way, from SparkLayer into QuickBooks.

| Data | Direction | Details |
| --- | --- | --- |
| Invoices | SparkLayer to QuickBooks | One invoice for each eligible B2B order, or for each shipment if you choose. Changes you make to an invoice in QuickBooks, such as to line items or customer details, aren't reflected back in SparkLayer or your platform. |
| Customers | SparkLayer to QuickBooks | Each invoice is linked to a matching QuickBooks customer. If there's no match, SparkLayer can create one. Details are copied once, when the customer is created. |
| Sales receipts | SparkLayer to QuickBooks | For orders paid upfront, if you turn on **Enable Sales Receipts**. |

### How invoices are created

SparkLayer creates the invoice in QuickBooks as soon as an eligible order arrives from your platform. This happens in the background so checkout stays fast, so the invoice can take a short while to appear in QuickBooks.

#### Which orders get an invoice

An order gets an invoice when both of these are true:

- **Fulfilment status is `processing` or `shipped`.** Orders that haven't reached `processing` yet, such as Shopify draft orders you haven't completed, don't get an invoice.
- **Paid with Payment by Invoice or Payment on Account.** Payment by Invoice orders are invoiced as soon as they reach `processing`. Pay on Account orders follow the **Payment on account - Invoice creation trigger** setting. See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md) to set these methods up.

The integration only covers B2B orders placed through SparkLayer. Retail (D2C) orders aren't sent to QuickBooks.

#### Pay on Account orders and split shipments

| Setting | When invoices are created |
| --- | --- |
| **On order** | One invoice for the whole order, when it reaches `processing`. |
| **On shipment** | One invoice each time a fulfilment is completed, containing only the items in that fulfilment. This handles split shipments. |

Customers can download every invoice for an order from **My Account**. With split shipments, the order's shipping is always added to the invoice for the **first** shipment.

If you switch from **On shipment** to **On order**, partly fulfilled orders won't get invoices for their remaining shipments. Complete any partly fulfilled orders before you change the setting.

#### What's on the invoice

| Field | Where it comes from |
| --- | --- |
| **Contact** | The QuickBooks customer matched (or created) from the order's customer. See [Contact matching and creation](#contact-matching-and-creation). |
| **Billing address** | The order's billing address. |
| **Due date (Payment by Invoice)** | The order date. |
| **Due date (Payment on Account)** | Worked out in this order: 1) the customer's [net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) in SparkLayer, added to the order date; 2) the customer's payment terms in QuickBooks; 3) your global payment terms in QuickBooks; 4) otherwise, the order date. |
| **Line description** | The item's SKU. |
| **Quantity** | The quantity on the SparkLayer order. |
| **Unit amount and line amount** | Calculated by SparkLayer and passed to QuickBooks. |
| **Tax amount** | Calculated by QuickBooks, using the tax rates set in QuickBooks. |
| **Shipping** | If shipping is turned on in QuickBooks, it's set on the invoice, with the shipping method named after the service chosen and the price in the totals. If it's off, shipping is added as a line item. The shipping line uses the **Shipping Tax Code**. |

### Contact matching and creation

Every invoice needs a QuickBooks customer. SparkLayer matches an existing one or, if you allow it, creates one.

#### How contacts are matched

When it creates an invoice, SparkLayer looks for the right QuickBooks customer in this order:

1. **Account number (recommended):** a QuickBooks customer whose ID matches the accounting ID [metafield](https://docs.sparklayer.io/help/customers/account-and-addresses.md#advanced-account-settings) on the SparkLayer customer.
2. **Email:** a QuickBooks customer with the same email address.

If either matches, the invoice is linked to that customer. If neither does, **Automatic Contact Creation** decides whether a new one is created.

#### Several contacts with one email

In SparkLayer, each email address belongs to one customer. In QuickBooks, several customers can share an email address. If more than one active QuickBooks customer has the email, and the invoice currency matches, the invoice goes to the oldest one. If your organisation has several contacts with the same email, give each a unique account number so matching is reliable.

#### Data synced when a contact is created

These details are copied once, when SparkLayer creates the QuickBooks customer. Later changes in SparkLayer aren't synced.

- First and last name
- Email address
- Billing and shipping address, from the order being invoiced
- Currency, set to the currency of the invoice

## Set up QuickBooks

Check the requirements, connect your QuickBooks company, then choose your settings.

### Requirements

- **The Pro or Enterprise plan.** See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
- **A Shopify store** connected to SparkLayer. See [Shopify](https://docs.sparklayer.io/help/platforms/shopify.md).
- **A QuickBooks Online account.** The desktop version isn't supported.
- **Your B2B products in QuickBooks**, each with a SKU that matches Shopify and the right tax rate.
- **Shipping turned on in QuickBooks**, if you want shipping added at invoice level. If it's off, shipping is added as a line item instead.

### Connect QuickBooks

1. In the SparkLayer Dashboard, go to **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.
2. Under **Accountancy**, turn on the switch next to **QuickBooks**.
3. Sign in to QuickBooks when it opens. QuickBooks shows the data SparkLayer needs access to (see the [FAQs](#faqs)).
4. If your QuickBooks account has several companies, choose the one to connect. You can connect one company per SparkLayer team.
5. Back in **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, open QuickBooks and complete the settings below.

When the integration is installed, SparkLayer creates a product called **SparkLayer Custom Product** in QuickBooks. It's used when a custom item is added to an order in SparkLayer. Before you use it, set its tax rate in QuickBooks, the same way as your other products. Otherwise invoices with custom items can't be created.

### Configure the integration

| Setting | What it does |
| --- | --- |
| **Automatic Contact Creation** | Not set when you install the integration: set it before you use the integration. Each invoice needs a QuickBooks customer. If SparkLayer can't [match an existing one](#how-contacts-are-matched), this decides what happens. **Enabled**: SparkLayer creates a new QuickBooks customer from the customer data it holds, the same way as the [Xero integration](https://docs.sparklayer.io/help/integrations/accountancy/xero.md). **Disabled**: SparkLayer doesn't create customers, because you create them in another system or manage them by hand in QuickBooks. If no match is found, no invoice is created. |
| **Payment on account - Invoice creation trigger** | Default: **On order**. When to create invoices for Pay on Account orders. **On order** creates one invoice for the whole order when it reaches `processing`. **On shipment** creates an invoice for each shipment, when it's fulfilled. See [Pay on Account orders and split shipments](#pay-on-account-orders-and-split-shipments). |
| **Enable Sales Receipts** | Creates sales receipts in QuickBooks for orders paid upfront. |
| **Shipping Tax Code** | The name of the QuickBooks tax code for the shipping line. You must set this for invoices to sync. |
| **Tax Exemption Tax Code** | The name of the QuickBooks tax code for invoice lines of tax-exempt customers. |
| **Income Account** | The name of the QuickBooks account to use as the income account for new products. It's used when SparkLayer creates the **SparkLayer Custom Product**. |

### Turn off the integration

1. In the SparkLayer Dashboard, go to **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.
2. Under **Accountancy**, turn off the switch next to **QuickBooks**.

When the integration is off:

- No invoices are created for orders placed while it's off.
- Customers can no longer open QuickBooks invoices created through SparkLayer from **My Account**.

## Limitations

- Products must exist in QuickBooks, with a SKU that matches Shopify and the correct tax rate.
- Invoice creation is one way. Changes to invoices in QuickBooks aren't reflected in SparkLayer or your platform.
- Apportioned tax rates on the shipping line aren't supported.
- Multi-currency isn't supported where a customer already has an invoice in another currency.

## FAQs

**How do I disconnect from QuickBooks?**

Turn the integration off in **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, under **Accountancy**. This removes the connection to your QuickBooks organisation. See [Turn off the integration](#turn-off-the-integration) for what happens next. It works the same way as the [Xero integration](https://docs.sparklayer.io/help/integrations/accountancy/xero.md).

**Does the integration work for D2C orders?**

No. It only covers B2B orders created through your platform's connection with SparkLayer. Direct-to-consumer (D2C) orders aren't sent to QuickBooks as invoices.

**What access does the integration need in QuickBooks?**

When you connect, QuickBooks lists the exact permissions SparkLayer asks for. We only ask for the minimum needed:

- **View & manage contacts**: to match invoices to existing contacts, and create new ones if your settings allow.
- **View & manage business transactions**: to create invoices for SparkLayer B2B orders and, in future, to view payments made on invoices.
- **View organisation settings**: to read settings such as global payment terms when working out due dates.

## Troubleshooting

If your issue isn't listed, or it continues after these steps, [contact support](https://docs.sparklayer.io/help/support.md).

**Customers can't see their invoice in My Account**

Check that:

- **The integration is turned on** in **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, under **Accountancy**.
- **The order is `processing` or `shipped`.** Orders that haven't reached `processing` yet, such as Shopify draft orders you haven't completed, don't get an invoice.
- **An invoice exists in QuickBooks** for the order. It can take a little while to sync. If there's a long delay, or no invoice was created, contact support with the customer and order ID.

If invoice links are missing for **all** your customers, contact support.


---

# Xero

URL: https://docs.sparklayer.io/help/integrations/accountancy/xero
Applies to: Shopify

Connect Xero to SparkLayer on Shopify to turn B2B orders into invoices and contacts, set account codes and tracking categories, and track invoice payments.

> **Quick summary**
>
> - The Xero integration creates an invoice in Xero for each B2B order paid by invoice or on account. It can create the Xero contact too, and brings payments on those invoices back to the SparkLayer order.
> - Invoices are created shortly after the order reaches **processing** (or, if you choose, as each shipment is fulfilled). Changes you make to an invoice in Xero don't come back to SparkLayer.
> - Connect it in the SparkLayer Dashboard at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, under **Accountancy**: turn on the switch and sign in to Xero. Needs the Pro or Enterprise plan and a Shopify store.
> - Customers can view and download their invoices from **My Account** on your store.

## What it does

[Xero](https://www.xero.com/) is online accounting software for managing finances, invoices and customer records.

SparkLayer has a direct integration with Xero. Your B2B orders sync to Xero as invoices and contacts, so there's less manual data entry and no need for another app to keep the systems in sync.

How a B2B order becomes a Xero invoice, and payments come back:

1. **B2B order**: Paid by invoice or on account, and processing or shipped
2. **Contact**: Matched by account number or email, or created
3. **Xero invoice**: Created in the background through the API
4. **Payments**: Payments and credit notes on the invoice update the SparkLayer order

### Let customers view invoices

When an invoice is ready, a **View & Download Invoice** button appears on the order in **My Account** on your store. It opens the public invoice page generated by Xero. If the button doesn't appear, see [Troubleshooting](#troubleshooting).

## What syncs and in which direction

Invoices and contacts go one way, from SparkLayer into Xero. Payments are the exception: they come back from Xero to the SparkLayer order.

| Data | Direction | Details |
| --- | --- | --- |
| Invoices | SparkLayer to Xero | One invoice for each eligible B2B order, or for each shipment if you choose. Changes you make to an invoice in Xero, such as to line items or customer details, aren't reflected back in SparkLayer or your platform. |
| Contacts | SparkLayer to Xero | Each invoice is linked to a matching Xero contact. If there's no match, SparkLayer can create one. Details are copied once, when the contact is created. |
| Payments | Xero to SparkLayer | Payments, credit notes and overpayments applied to the invoice update the SparkLayer order. See [Payment visibility](#payment-visibility). |

### How invoices are created

SparkLayer creates the invoice in Xero as soon as an eligible order arrives from your platform. This happens in the background so checkout stays fast, so the invoice can take a short while to appear in Xero. Each invoice has a note in its **History & Notes** in Xero showing it came from SparkLayer.

#### Which orders get an invoice

An order gets an invoice when both of these are true:

- **Fulfilment status is `processing` or `shipped`.** Orders that haven't reached `processing` yet, such as Shopify draft orders you haven't completed, don't get an invoice.
- **Paid with Payment by Invoice or Payment on Account.** Payment by Invoice orders are invoiced as soon as they reach `processing`. Pay on Account orders follow the **Invoice creation for Payment on account orders** setting. See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md) to set these methods up.

The integration only covers B2B orders placed through SparkLayer. Retail (D2C) orders aren't sent to Xero.

#### Pay on Account orders and split shipments

| Setting | When invoices are created |
| --- | --- |
| **On order** | One invoice for the whole order, when it reaches `processing`. |
| **On shipment** | One invoice each time a fulfilment is completed, containing only the items in that fulfilment. This handles split shipments. |

Customers can download every invoice for an order from **My Account**. With split shipments, the order's shipping is always added to the invoice for the **first** shipment.

Split shipments can sometimes cause rounding differences, because your platform, SparkLayer and Xero calculate tax across shipments slightly differently. When SparkLayer detects one, it adds a "Rounding adjustment" line to the invoice, using Xero's rounding account code `860`. The Xero invoice total then matches the SparkLayer order.

#### What's on the invoice

| Field | Where it comes from |
| --- | --- |
| **Status** | **Submitted** by default. **Draft** if SparkLayer can't work out a valid due date. |
| **Contact** | The Xero contact matched (or created) from the order's customer. See [Contact matching and creation](#contact-matching-and-creation). |
| **Billing address** | The billing address on the matched Xero contact. |
| **Due date (Payment by Invoice)** | The order date. |
| **Due date (Payment on Account)** | Worked out in this order: 1) the customer's [net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) in SparkLayer, added to the order date; 2) the contact's payment terms in Xero; 3) your global payment terms in Xero; 4) otherwise, the order date. |
| **Item code** | The line's SKU, if **Map Line Items to Item Codes** is enabled. |
| **Account code** | The **Default Line Item Account Code**. |
| **Description** | The line's SKU and parent and child product names, plus any custom attributes. |
| **Quantity** | The quantity on the SparkLayer order. |
| **Unit amount, line amount and tax amount** | Calculated by SparkLayer and passed to Xero. |
| **Shipping** | A line at the bottom of the invoice, described with the shipping method name and SKU, using the **Shipping Line Account Code** (or the default account code). |
| **Tracking** | If you've set **Tracking categories**, every line gets those categories (up to 2). |

Xero allows one billing address per contact. If a SparkLayer customer has several addresses, the address on the invoice may differ from the one they used. SparkLayer only copies the billing address when it creates the contact, so later changes in SparkLayer need updating by hand on the invoice or the Xero contact.

### Contact matching and creation

Every invoice needs a Xero contact. SparkLayer matches an existing one or, if you allow it, creates one.

#### How contacts are matched

When it creates an invoice, SparkLayer looks for the right Xero contact in this order:

1. **Account number:** a Xero contact whose account number matches the accounting ID on the SparkLayer customer. See [how to set accounting IDs](https://docs.sparklayer.io/help/customers/account-and-addresses.md#advanced-account-settings).
2. **Email:** a Xero contact with the same email address.

If either matches, the invoice is linked to that contact. If neither does, **Automatic Contact Creation** decides whether a new one is created.

#### Several contacts with one email

In SparkLayer, each email address belongs to one customer. In Xero, several contacts can share an email address. If they do, the invoice goes to the first matching contact Xero returns. If your organisation has several contacts with the same email, give each a unique account number so matching is reliable.

#### Data synced when a contact is created

These details are copied once, when SparkLayer creates the Xero contact. Later changes in SparkLayer aren't synced.

- Company name
- First and last name
- Email address
- Billing and shipping address, from the order being invoiced
- Payment terms, if set with the payment terms [metafield](https://docs.sparklayer.io/help/glossary.md#metafields). Contacts are created with Xero's _days after bill date_ payment term type.

#### Contact names

Xero needs every contact **name** to be unique, so SparkLayer tries these names in turn:

1. The [company name](https://docs.sparklayer.io/help/customers/account-and-addresses.md#advanced-account-settings) metafield, if it's filled in. For example, "The Company".
2. If that name is taken, the company name followed by the customer's first and last name. For example, "The Company (Jane Doe)".
3. If that's also taken, the customer's first and last name. For example, "Jane Doe".

If all of these are taken, SparkLayer tries them again with a timestamp added, for example "The Company (20260520093837)", so the invoice can still be created.

### Payment visibility

If [payment visibility](https://docs.sparklayer.io/help/ordering/payment-methods.md#payments-visibility) is turned on, payments made against invoices in Xero show as transactions on the SparkLayer order. SparkLayer tracks:

- Payments and offline payments
- Credit notes applied to invoices
- Overpayments applied to invoices

Each one appears as a transaction on the order and changes the balance due. SparkLayer keeps tracking Xero payments in the background even when payment visibility is off.

#### Refunds

Refunds on card payments aren't tracked, because they're usually recorded as a credit note on the customer's account rather than applied to an invoice. If one of the payment types above is removed from an invoice, SparkLayer updates the order to match.

#### Credit limits

If you use [credit limits and account balances](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md), payments on Xero invoices for Pay on Account orders reduce the customer's unpaid balance automatically.

Credit limits set on contacts in Xero aren't available through the Xero API, so SparkLayer can't sync them. Set credit limits in SparkLayer instead: see [Credit limits and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md).

#### Credit notes

Credit applied to an invoice syncs as a payment. Unallocated credit on a Xero contact doesn't sync to the customer's balance in SparkLayer. To keep them in step, adjust the balance in the customer's metafield by hand to reflect the unallocated credit. Change it back once you've allocated the credit to an invoice.

## Common workflows

| You want | What to do |
| --- | --- |
| **An invoice as soon as the order is confirmed** (the default) | Nothing. When the order reaches `processing`, SparkLayer creates the Xero invoice automatically. |
| **Payment before you process the order** | This isn't automatic. Either move the order to `processing` without fulfilling it, for example by completing the Shopify draft order with payment due later, so Xero creates the invoice. Then fulfil it once the customer has paid. Or create the invoice by hand in Xero. |

For the first option on a Pay on Account order, **Invoice creation for Payment on account orders** must be **On order**. With **On shipment**, the invoice is only created when you fulfil. See [Configure the integration](#configure-the-integration).

On Shopify, an order paid by invoice or on account moves through these stages:

From draft order to Xero invoice and fulfilment:

1. **Draft order**: The order arrives as a Shopify draft order
2. **Complete the draft**: Mark it as paid, or complete it with payment due later
3. **Processing**: It's now a completed Shopify order
4. **Xero invoice**: SparkLayer creates the invoice
5. **Fulfil**: You ship the order

Marking a draft order as paid in Shopify turns it into a completed order, but doesn't fulfil it. See [Complete a draft order by hand](https://docs.sparklayer.io/help/ordering/automation-and-workflows.md#complete-a-draft-order-by-hand).

## Set up Xero

Check the requirements, connect your Xero organisation, then choose your settings.

### Requirements

- **The Pro or Enterprise plan.** See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
- **A Shopify store** connected to SparkLayer. See [Shopify](https://docs.sparklayer.io/help/platforms/shopify.md).
- **A Xero organisation** to connect.

### Connect Xero

1. In the SparkLayer Dashboard, go to **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.
2. Under **Accountancy**, turn on the switch next to **Xero**.
3. Sign in to Xero when it opens. Xero shows the data SparkLayer needs access to (see the [FAQs](#faqs)).
4. If your Xero account has several organisations, choose the one to connect. You can connect one organisation to your SparkLayer Dashboard.
5. Back in **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, open Xero and complete the settings below.

### Configure the integration

| Setting | What it does |
| --- | --- |
| **Automatic Contact Creation** | Default: **Disabled**. Each invoice needs a Xero contact. If SparkLayer can't [match an existing one](#how-contacts-are-matched), this decides what happens. **Enabled**: SparkLayer creates a new Xero contact from the customer data it holds (see [Contact matching and creation](#contact-matching-and-creation)). **Disabled**: SparkLayer doesn't create contacts, because you create them in another system or manage them by hand in Xero. If no match is found, the invoice may fail. |
| **Default Line Item Account Code** | Default: `200`. The Xero account code for invoice line items. Find your account codes in **Chart of Accounts** in Xero. |
| **Shipping Line Account Code** | The Xero account code for shipping lines, for example `260`. If you leave it empty, the **Default Line Item Account Code** is used. |
| **Invoice creation for Payment on account orders** | Default: **On order**. When to create invoices for Pay on Account orders. **On order** creates one invoice for the whole order when it reaches `processing`. **On shipment** creates an invoice for each shipment, when it's fulfilled. See [Pay on Account orders and split shipments](#pay-on-account-orders-and-split-shipments). |
| **Invoice Line Item Mapping** | Contains **Map Line Items to Item Codes**. Default: **Disabled**. When enabled, each invoice line is linked to the Xero item (product) whose item code matches the line's SKU in SparkLayer. If no Xero item has that SKU, the invoice isn't created. See [Map line items to Xero items](#map-line-items-to-xero-items). |
| **Tracking categories** | Default: none. The Xero tracking categories to set on every invoice line, as comma-separated `CategoryName:Option` pairs. For example, `Channel:B2B,Source:SparkLayer` sets the **Channel** category to **B2B** and the **Source** category to **SparkLayer**. Xero allows up to 2 tracking categories per line: any more are ignored. |

### Map line items to Xero items

If you've already created an item in Xero for every product, using the product SKU as the Xero item code, you can link invoice lines to those items:

1. In **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, open Xero.
2. Under **Invoice Line Item Mapping**, turn on **Map Line Items to Item Codes**.

If a line's SKU doesn't exist as an item in Xero, the invoice isn't created. Once you add the missing item, the invoice is created.

### Turn off the integration

1. In the SparkLayer Dashboard, go to **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.
2. Under **Accountancy**, turn off the switch next to **Xero**.

When the integration is off:

- No invoices are created for orders placed while it's off.
- Customers can no longer open their Xero invoices from **My Account**.

## Limitations

- Multiple tax rates on one line item aren't supported.
- Invoice creation is one way. Changes to invoices in Xero, such as to line items or customer details, aren't reflected in SparkLayer or your platform.
- Xero credit limits and unallocated credit don't sync (see [Payment visibility](#payment-visibility)).

## FAQs

**How do I disconnect from Xero?**

Turn the integration off in **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, under **Accountancy**. This removes the connection to your Xero organisation. See [Turn off the integration](#turn-off-the-integration) for what happens next.

**Does the integration work for D2C orders?**

No. It only covers B2B orders created through your platform's connection with SparkLayer. Direct-to-consumer (D2C) orders aren't sent to Xero as invoices.

**What access does the integration need in Xero?**

When you connect, Xero lists the exact permissions SparkLayer asks for. We follow Xero's best practice and only ask for the minimum needed:

- **View & manage contacts**: to match invoices to existing contacts, and create new ones if your settings allow.
- **View & manage business transactions**: to create invoices for SparkLayer B2B orders and, in future, to view payments made on invoices. 
- **View organisation settings**: to read settings such as global payment terms when working out due dates.

## Troubleshooting

If your issue isn't listed, or it continues after these steps, [contact support](https://docs.sparklayer.io/help/support.md).

**Customers can't see their invoice in My Account**

Check that:

- **The integration is turned on** in **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, under **Accountancy**.
- **The order is `processing` or `shipped`.** Orders that haven't reached `processing` yet, such as Shopify draft orders you haven't completed, don't get an invoice.
- **An invoice exists in Xero** for the order. It can take a little while to sync. If there's a long delay, or no invoice was created, contact support with the customer and order ID.
- **The invoice isn't a Draft.** Xero doesn't give draft invoices a public link.

If invoice links are missing for **all** your customers, contact support.

**The address on the invoice is different from the one used at checkout**

Invoice addresses come from the Xero contact. SparkLayer lets a customer have several billing and shipping addresses, but Xero allows one of each per contact.

SparkLayer only uses its own addresses when it creates the contact. If the addresses change afterwards, they aren't updated in Xero automatically.


---

# Shipping and invoicing apps

URL: https://docs.sparklayer.io/help/integrations/customer-experience

Add Sufio invoices or Intuitive Shipping rates to your SparkLayer B2B store, with what each app needs, which platforms it works on and how to set it up.

> **Quick summary**
>
> - These apps add to what B2B customers see on your store: professional invoices (Sufio) and customer-specific shipping rates (Intuitive Shipping).
> - Sufio and Intuitive Shipping connect to SparkLayer in the SparkLayer Dashboard at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.
> - You need the partner's own app installed first. Sufio is for Shopify; Intuitive Shipping works on Shopify and BigCommerce.

Each app adds one thing to what your B2B customers see:

| App | What it adds | Where you set it up | Platforms |
| --- | --- | --- | --- |
| [Sufio](https://docs.sparklayer.io/help/integrations/customer-experience/sufio.md) | A **View & Download Invoice** button on orders in My Account | **Invoicing** in Partners | Shopify |
| [Intuitive Shipping](https://docs.sparklayer.io/help/integrations/customer-experience/intuitive-shipping.md) | Your Intuitive Shipping rates in the SparkLayer checkout | **Shipping** in Partners | Shopify, BigCommerce |

- [Sufio invoicing](https://docs.sparklayer.io/help/integrations/customer-experience/sufio.md): Professional invoices · Direct integration
- [Intuitive Shipping](https://docs.sparklayer.io/help/integrations/customer-experience/intuitive-shipping.md): Advanced shipping · Direct integration


---

# Intuitive Shipping

URL: https://docs.sparklayer.io/help/integrations/customer-experience/intuitive-shipping
Applies to: Shopify, BigCommerce

Show your Intuitive Shipping rates to B2B customers in the SparkLayer checkout on Shopify or BigCommerce, with setup steps, testing and known limitations.

> **Quick summary**
>
> - The Intuitive Shipping integration shows the shipping rates you set up in Intuitive Shipping to B2B customers in the SparkLayer checkout.
> - Turn it on in the SparkLayer Dashboard at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, under **Shipping**, with your Intuitive Shipping API key.
> - Needs an Intuitive Shipping account and a Shopify or BigCommerce store. SparkLayer's own shipping must be turned on too.

## What it does

[Intuitive Shipping](https://intuitiveshipping.com/) is a shipping app for eCommerce platforms such as Shopify and BigCommerce, for managing shipping rules on your store.

With the integration, the rates you set up in Intuitive Shipping show in the SparkLayer checkout, where B2B customers choose one.

How Intuitive Shipping rates reach the SparkLayer checkout:

1. **Intuitive Shipping**: You set up your shipping rates and rules
2. **SparkLayer**: Fetches the rates using your API key
3. **Checkout**: B2B customers choose a rate at Review & Pay

## What syncs and in which direction

Rates go one way, from Intuitive Shipping into the SparkLayer checkout, each time a customer checks out.

| Data | Direction | Details |
| --- | --- | --- |
| Shipping rates | Intuitive Shipping to the SparkLayer checkout | SparkLayer fetches your rates using your API key. B2B customers see them under **Shipping Method** at **Review & Pay**. |

## Set up Intuitive Shipping

Check the requirements, connect Intuitive Shipping with its API key, then test it at checkout.

### Requirements

- **An Intuitive Shipping account**, with the [Intuitive Shipping app](https://apps.shopify.com/intuitive-shipping) installed on your store.
- **A Shopify or BigCommerce store** connected to SparkLayer.
- **SparkLayer shipping turned on**: **Use SparkLayer shipping rates** ticked in **Settings > Shipping** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping** in the Shopify app (see [shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md)). This stops your eCommerce platform's own shipping methods showing in the SparkLayer checkout.

### Connect Intuitive Shipping

1. In your Intuitive Shipping dashboard, go to **Settings > Partner Integrations** and copy the **API Key**.
2. In the SparkLayer Dashboard, go to **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.
3. Under **Shipping**, turn on the switch next to **Intuitive Shipping**.
4. Paste the key into **API Key** and click **Save**.

### Test the integration

1. Sign in to your store as a B2B customer.
2. Go through checkout until you reach **Review & Pay**.
3. Under **Shipping Method**, check you see the rates you set up in Intuitive Shipping, for example **Standard**, **Priority** and **Overnight**, each with its delivery time and price.

## Limitations

- **Shipping dates** set up in Intuitive Shipping aren't used.
- Only physical products are supported, not digital products.
- Shipping prices are always shown net (excluding tax).


---

# Sufio invoicing

URL: https://docs.sparklayer.io/help/integrations/customer-experience/sufio
Applies to: Shopify

Connect Sufio to SparkLayer on Shopify so B2B customers can view and download their Sufio invoices from My Account, with setup, testing and limitations.

> **Quick summary**
>
> - The Sufio integration adds a **View & Download Invoice** button to each order in the SparkLayer **My Account** area. It opens the customer's Sufio invoice.
> - Turn it on in the SparkLayer Dashboard at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, under **Invoicing**. There's nothing else to set up.
> - Needs a Sufio account with the Sufio app installed on your Shopify store.
> - SparkLayer also has its own invoicing: see [Invoices](https://docs.sparklayer.io/help/ordering/invoices.md).

## What it does

[Sufio](https://sufio.com/shopify/invoice/?ref=sparklayer-2) is an invoicing app for eCommerce platforms such as Shopify and BigCommerce. It creates designed invoices, with features such as a customisable design and support for multiple currencies. See Sufio in the [Shopify App Store](https://apps.shopify.com/sufio).

With the integration, B2B customers can open the invoice for each order they place from the order in [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md#order-history). They click **View & Download Invoice** on the order and go to their Sufio invoice, where they can see the details and download it as a PDF.

To see it in action, sign in to our [B2B demo store](https://b2b-demo-store-usd.myshopify.com/pages/b2b-login-register) and open an order in **My Account**.

## What syncs and in which direction

Your invoices stay in Sufio. SparkLayer links to them from each order.

| Data | Direction | Details |
| --- | --- | --- |
| Invoices | Sufio to My Account | For each order, a **View & Download Invoice** button in My Account opens the customer's Sufio invoice. |

Sufio can also email customers a copy of their invoice and send reminders. See Sufio's guide to [custom invoice sending](https://sufio.com/articles/shopify/send-invoices-customers/when-send-invoices/custom/).

## Set up Sufio

Check the requirements, turn on the integration, then place a test order.

### Requirements

- **A Sufio account**, with the [Sufio Shopify app](https://apps.shopify.com/sufio) installed on your store.
- **A Shopify store** connected to SparkLayer. See [Shopify](https://docs.sparklayer.io/help/platforms/shopify.md).

### Connect Sufio

1. Install the Sufio app on your Shopify store, if you haven't already.
2. In the SparkLayer Dashboard, go to **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.
3. Under **Invoicing**, turn on the switch next to **Sufio**.

There's nothing else to set up.

### Test the integration

1. Sign in to your store as a B2B customer.
2. Place an order with one of the available payment methods.
3. If you used an offline payment method, such as Pay by Invoice, complete the draft order in the Shopify admin so it appears in **Orders** ([open in the Shopify admin](https://admin.shopify.com/orders)).
4. On your store, as the B2B customer, open **My Account** and click the order.
5. Check the **View & Download Invoice** button is there.

## Limitations

- If you're installing Sufio for the first time, invoices only show for **new** orders.

To attach invoices to orders by hand instead, see [Credit limits and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md).


---

# Plans and features

URL: https://docs.sparklayer.io/help/plans-and-features

Compare SparkLayer's Basic, Starter, Growth, Pro and Enterprise plans: order allowances, sales agents, add-ons and which B2B features each plan includes.

> **Quick summary**
>
> - SparkLayer has a free **Basic** plan (Shopify only) and 4 paid plans: **Starter** ($49 per month), **Growth** ($149), **Pro** ($299) and **Enterprise** (from $499). Every paid plan has a 14-day free trial, and each includes everything in the plan below it.
> - Plans differ by B2B orders per month (5 to 150, or custom on Enterprise), price lists (3 on Basic, unlimited above), sales agents and features. Starter adds sales agents, the [Intelligent Cart](https://docs.sparklayer.io/help/ordering/intelligent-cart.md)'s AI file upload and barcode scanning, the [Catalog](https://docs.sparklayer.io/help/sales-ordering/catalog.md), [Counter mode](https://docs.sparklayer.io/help/sales-ordering/counter-mode.md) and SparkLayer shipping rates. Growth adds [SparkLayer Invoices](https://docs.sparklayer.io/help/ordering/invoices.md) (automatic PDF invoices, payment reminders and your own invoice template), B2B discounts, stock locations and form workflow automations. Pro adds quotes (the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md), also a $49 per month add-on on Starter and Growth), the SparkLayer API (for connecting systems such as an ERP), test mode, sending emails from your own domain, and Xero and QuickBooks Online. Enterprise adds 24/7 support with a service level agreement (SLA), Ignite (for connecting other platforms) and the Magento integration.
> - [Forms](https://docs.sparklayer.io/help/forms.md), [net terms](https://docs.sparklayer.io/help/glossary.md#net-terms), credit limits, Pay on Account and Pay by Invoice (see [Credit limits and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md)), free installation help, [companies](https://docs.sparklayer.io/help/customers/companies.md) and [email and translation templates](https://docs.sparklayer.io/help/dashboard/settings.md#templates) are on every plan.
> - Check or change your plan at **Plan card** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Plan** in the Shopify app. See [Your plan and usage](https://docs.sparklayer.io/help/dashboard/plan-and-features.md).

Use this page to compare plans before you choose one, or to check which plan a feature needs. Each paid plan adds more orders, more sales agents and extra features to the plan below it. Every feature links to its guide.

> **Check the pricing page for the latest plans**
>
> Plans, prices and features can change. The [SparkLayer pricing page](https://www.sparklayer.io/pricing/) is always the source of truth.

## Plans at a glance

| Plan | Price | B2B orders per month | Price lists | Sales agents included |
| --- | --- | --- | --- | --- |
| Basic | Free | 5 | 3 | 0 |
| Starter | $49 per month | 50 | Unlimited | 1 |
| Growth | $149 per month | 100 | Unlimited | 2 |
| Pro | $299 per month | 150 | Unlimited | 5 |
| Enterprise | From $499 per month | Custom | Unlimited | Custom |

- Every paid plan comes with a 14-day free trial.
- The free Basic plan is only available on Shopify. Stores on Wix and other platforms start with a 14-day free trial of a paid plan instead.
- The Magento integration needs the Enterprise plan. See [Magento FAQs](https://docs.sparklayer.io/help/platforms/magento/faqs.md).
- Subscriptions are billed in US dollars. Shopify merchants are billed through Shopify. For each platform, trials, downgrading and cancelling, see [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md).
- Your plan and this month's usage are on your [plan card](https://docs.sparklayer.io/help/dashboard/plan-and-features.md#your-plan).

### What counts as a B2B order

Only orders placed through SparkLayer count towards your order allowance. Retail orders placed through the same store don't count. Orders that are later cancelled or refunded still count.

If you go over your allowance, nothing is blocked. SparkLayer keeps working, and your plan card shows **Over limit**. Our team will get in touch to talk about whether another plan would suit you better. 

## Add-ons

| Add-on | Availability |
| --- | --- |
| [Sales agents](https://docs.sparklayer.io/help/sales-reps.md#plans-and-limits) | $39 per month for each additional sales agent. |
| [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md) | Free on every plan (Shopify only). |
| [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md) | $49 per month on Starter and Growth. Included on Pro and Enterprise. Not available on Basic: reviewing quotes needs a sales agent or Sales administrator, and sales agents start on Starter. |

## Feature comparison

✓ means the feature is included on that plan. – means it isn't. Add-on means you can add it to that plan for a monthly fee (see [Add-ons](#add-ons)).

### Advanced features

| Feature | Basic | Starter | Growth | Pro | Enterprise |
| --- | --- | --- | --- | --- | --- |
| [Intelligent Cart (AI)](https://docs.sparklayer.io/help/ordering/intelligent-cart.md): **Upload a file** with AI (PDFs, photos and emails) and camera barcode scanning | – | ✓ | ✓ | ✓ | ✓ |
| [Sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md) | – | ✓ | ✓ | ✓ | ✓ |
| [Quotes](https://docs.sparklayer.io/help/ordering/quoting.md) (the Quoting Engine) | – | Add-on | Add-on | ✓ | ✓ |
| [Forms](https://docs.sparklayer.io/help/forms.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Form workflow automations](https://docs.sparklayer.io/help/forms/workflows.md) | – | – | ✓ | ✓ | ✓ |
| [Companies](https://docs.sparklayer.io/help/customers/companies.md) and [company locations](https://docs.sparklayer.io/help/customers/company-locations.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Company users](https://docs.sparklayer.io/help/customers/company-users.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Advanced discounts](https://docs.sparklayer.io/help/pricing/discounts.md) | – | – | ✓ | ✓ | ✓ |
| [SparkLayer Invoices](https://docs.sparklayer.io/help/ordering/invoices.md) (automatic PDF invoices, payment reminders and your own invoice template) | – | – | ✓ | ✓ | ✓ |
| [Stock (inventory) locations](https://docs.sparklayer.io/help/storefront/stock-display.md#stock-locations-inventory-locations) | – | – | ✓ | ✓ | ✓ |
| [File uploads at checkout](https://docs.sparklayer.io/help/ordering/checkout-fields.md#file-upload-file-attachments) | – | – | ✓ | ✓ | ✓ |
| Remove "Powered by SparkLayer" branding | – | – | ✓ | ✓ | ✓ |
| [Order approval workflows](https://docs.sparklayer.io/help/customers/company-users.md) | – | – | ✓ | ✓ | ✓ |
| [SparkLayer API](https://docs.sparklayer.io/developers/api.md) | – | – | – | ✓ | ✓ |
| [Test mode](https://docs.sparklayer.io/help/dashboard/test-mode.md) | – | – | – | ✓ | ✓ |
| [Xero](https://docs.sparklayer.io/help/integrations/accountancy/xero.md) and [QuickBooks Online](https://docs.sparklayer.io/help/integrations/accountancy/quickbooks.md) | – | – | – | ✓ | ✓ |
| [ERP integrations](https://docs.sparklayer.io/help/integrations/erps.md) (Brightpearl, Cin7 Core, Katana, Linnworks and Unleashed) | – | – | – | ✓ | ✓ |

### Pricing and product rules

| Feature | Basic | Starter | Growth | Pro | Enterprise |
| --- | --- | --- | --- | --- | --- |
| [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md) (automatic and manual) | Up to 3 | Unlimited | Unlimited | Unlimited | Unlimited |
| [Customer-specific pricing](https://docs.sparklayer.io/help/pricing/customer-pricing.md) and percentage discounts | ✓ | ✓ | ✓ | ✓ | ✓ |
| Multiple price lists per customer | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Multi-currency price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [RRP (MSRP) display](https://docs.sparklayer.io/help/pricing/pricing-display.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Pricing from a backend system via the API (e.g. an ERP) | – | – | – | ✓ | ✓ |
| [Coupons and discount codes](https://docs.sparklayer.io/help/pricing/discounts.md) | – | – | ✓ | ✓ | ✓ |
| [Free product discounts](https://docs.sparklayer.io/help/pricing/discounts.md) | – | – | ✓ | ✓ | ✓ |
| [Pack sizes and minimum or maximum quantities](https://docs.sparklayer.io/help/storefront/quantity-rules.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Unit of measure pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Product customisations](https://docs.sparklayer.io/help/storefront/product-display.md#product-customisations) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Net price display | ✓ | ✓ | ✓ | ✓ | ✓ |

### Customer self-service

| Feature | Basic | Starter | Growth | Pro | Enterprise |
| --- | --- | --- | --- | --- | --- |
| [Shopping lists](https://docs.sparklayer.io/help/ordering/shopping-lists.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Quick ordering and re-ordering | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Import a CSV or spreadsheet of SKUs to the cart](https://docs.sparklayer.io/help/ordering/intelligent-cart.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Order history, tracking and purchase reports](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Address book management](https://docs.sparklayer.io/help/customers/account-and-addresses.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Credit limits and account balances](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Customer-specific payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Checkout](https://docs.sparklayer.io/help/ordering/checkout-fields.md) and account custom fields | ✓ | ✓ | ✓ | ✓ | ✓ |
| Stock reservation for retail (B2C) customers | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Tax handling](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md) | ✓ | ✓ | ✓ | ✓ | ✓ |

### Orders

| Feature | Basic | Starter | Growth | Pro | Enterprise |
| --- | --- | --- | --- | --- | --- |
| [Pay by Invoice](https://docs.sparklayer.io/help/ordering/payment-methods.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Pay on Account](https://docs.sparklayer.io/help/ordering/payment-methods.md), with credit limits | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Net terms](https://docs.sparklayer.io/help/glossary.md#net-terms), such as Net 30 | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Payment method rules](https://docs.sparklayer.io/help/ordering/payment-method-rules.md) (discounts, surcharges and hiding methods, Shopify only) | – | – | ✓ | ✓ | ✓ |
| [Request for quote](https://docs.sparklayer.io/help/ordering/quoting.md) | – | Add-on | Add-on | ✓ | ✓ |
| [Minimum and maximum order totals](https://docs.sparklayer.io/help/storefront/quantity-rules.md#order-limit-rules) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [B2B-specific shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md) | – | ✓ | ✓ | ✓ | ✓ |
| Orders routed as draft or completed orders | ✓ | ✓ | ✓ | ✓ | ✓ |

### Sales agent ordering

These features need at least one sales agent, so they start on the Starter plan.

| Feature | Basic | Starter | Growth | Pro | Enterprise |
| --- | --- | --- | --- | --- | --- |
| Place orders on behalf of a customer at their B2B prices | – | ✓ | ✓ | ✓ | ✓ |
| Create new customers | – | ✓ | ✓ | ✓ | ✓ |
| View a customer's order history and re-order | – | ✓ | ✓ | ✓ | ✓ |
| Manage shopping lists for a customer | – | ✓ | ✓ | ✓ | ✓ |
| [Catalog](https://docs.sparklayer.io/help/sales-ordering/catalog.md) (Quick Order) | – | ✓ | ✓ | ✓ | ✓ |
| [Counter mode](https://docs.sparklayer.io/help/sales-ordering/counter-mode.md) | – | ✓ | ✓ | ✓ | ✓ |

### Store setup and support

| Feature | Basic | Starter | Growth | Pro | Enterprise |
| --- | --- | --- | --- | --- | --- |
| Run retail (B2C) and B2B from one store | ✓ | ✓ | ✓ | ✓ | ✓ |
| Ready-made [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md), optimised for mobile and tablet | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Full customisation of the frontend](https://docs.sparklayer.io/help/storefront/customising-design.md) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Templates](https://docs.sparklayer.io/help/dashboard/settings.md#templates) for your own emails and translations | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Invoice templates](https://docs.sparklayer.io/help/ordering/invoices.md#change-the-invoice-design-with-theming) (your own invoice design, part of SparkLayer Invoices) | – | – | ✓ | ✓ | ✓ |
| [Custom email domain](https://docs.sparklayer.io/help/customers/timeline.md#send-emails-from-your-own-domain) (send emails from your own domain) | – | – | – | ✓ | ✓ |
| [Support by email and chat](https://docs.sparklayer.io/help/support.md#response-times) (replies within 24 hours on weekdays) | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Free installation help](https://docs.sparklayer.io/help/support.md#request-free-installation) (our team installs the storefront widgets) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Personalised onboarding sessions | – | ✓ | ✓ | ✓ | ✓ |
| Dedicated consultation, technical support and systems integrations | – | – | – | – | ✓ |
| 24/7 support with an SLA, on top of standard support | – | – | – | – | ✓ |
| [SparkLayer Ignite](https://docs.sparklayer.io/ignite.md), for connecting platforms without a ready-made integration | – | – | – | – | ✓ |

## Changing your plan

Change your plan at **Plan card** in the SparkLayer Dashboard, or **SparkLayer Wholesale > Plan** in the Shopify app. On Shopify, you then confirm the change in your Shopify admin. Every paid plan starts with a 14-day free trial. See [Change your plan](https://docs.sparklayer.io/help/dashboard/plan-and-features.md#change-your-plan), and for downgrading, cancelling and what happens when a trial ends, [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md).

A feature your plan doesn't include shows the plan it needs and an **Unlock** button. See [Unlock a feature](https://docs.sparklayer.io/help/dashboard/plan-and-features.md#unlock-a-feature).

To discuss the Enterprise plan, [book a demo](https://www.sparklayer.io/demo/) with our team.


---

# Contact support

URL: https://docs.sparklayer.io/help/support

Contact SparkLayer support by email or Dashboard chat, see how fast we reply, get free widget installation or an onboarding session, and check what we cover.

> **Quick summary**
>
> - Email [support@sparklayer.io](mailto:support@sparklayer.io), or click the message icon in the [SparkLayer Dashboard](https://app.sparklayer.io/) or at the bottom right of this page.
> - We reply within 24 hours on weekdays, and within 48–72 hours at weekends. The Enterprise plan adds 24/7 support with a service level agreement (SLA). See [Response times](#response-times).
> - On every plan, our team installs SparkLayer's storefront widgets for you, free. Paid plans also include personalised onboarding sessions.
> - We support SparkLayer's features, installation and settings. We don't cover problems caused by third-party apps or your theme.
> - If something has stopped working for everyone, check [SparkLayer's status page](https://status.sparklayer.io/) first: it shows any incident and when it's fixed.

## Contact support

Contact our team for help with SparkLayer, including setting it up on your website:

- Email [support@sparklayer.io](mailto:support@sparklayer.io), or
- Click the message icon (a purple speech bubble) in the [SparkLayer Dashboard](https://app.sparklayer.io/), or at the bottom right of this page.

Many common problems, such as missing B2B prices or widgets not loading, have a quick fix in [Troubleshooting](https://docs.sparklayer.io/help/troubleshooting.md).

So we can help quickly, include:

- **Which store it's about**, such as your store's web address.
- **What your query is about**, in as much detail as you can.
- **Screenshots** that help show the problem.

## Response times

| Plan | When we reply |
| --- | --- |
| **Every plan** | Within 24 hours on weekdays, and within 48–72 hours at weekends. |
| **Enterprise** | 24/7 support, with a service level agreement (SLA) on top. Contact us for its details. |

The message icon isn't a live chat that's always staffed, so you won't always get a reply in real time. Our team often replies well within these times, with a solution.

## Get help with onboarding

| Help | Plans |
| --- | --- |
| **Free installation**: our team adds SparkLayer's storefront widgets to your website and tests them. See [Request free installation](#request-free-installation). | Every plan |
| **Personalised onboarding sessions**: a video call with our onboarding team to walk you through setting up your data and features. [Book an onboarding call](https://book.sparklayer.io/). | Paid plans (Starter and above) |

To ask a question at any time, click the message icon to contact the team.

You can also reach us from the app:

| Where | Button | What it does |
| --- | --- | --- |
| **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app | **Book setup call** | Books a free setup call with our onboarding team. |
| **Home > Setup** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale > Setup** in the Shopify app | **Chat with support** | Opens a chat with our team. |
| **Home** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/)), or **SparkLayer Wholesale** in the Shopify app, at the foot | **Book free setup** | Books a free setup call. |
| **Settings > Configurations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations** in the Shopify app, at the top | **Free setup assistance** | Books a free setup call. |

### Request free installation

Your website needs SparkLayer's [storefront interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) installed. Our team does this for you, free of charge:

1. 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. Under **Ask us to install it**, click **Request installation**. On Shopify, you can also click **Something not right? Install SparkLayer for me** in [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md).
2. We get in touch within a working day, and ask for access to your website so we can edit your code.
3. We install all the SparkLayer storefront interfaces you need and test that everything works.
4. We let you know when it's ready. Test it yourself with the [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md). On a paid plan, you can also [book an onboarding call](https://book.sparklayer.io/) to talk through any questions.

## What our support covers

| Covered | Not covered |
| --- | --- |
| Questions about our apps' functionality, integration and installation | Problems caused by third-party plugins |
| Help configuring app settings | Anything your theme developer supports, such as native theme settings and design decisions |
| Bugs you've found | |

If we don't cover your query, we'll try to point you to the best place to get help.

## Check SparkLayer's status

If the SparkLayer Dashboard, your storefront widgets or the APIs stop working, check [status.sparklayer.io](https://status.sparklayer.io/). It shows whether each part of SparkLayer is running normally, and any incident we're working on, with updates until it's fixed. If the status page shows nothing wrong, [contact us](#contact-support).

## Other help

- [Troubleshooting](https://docs.sparklayer.io/help/troubleshooting.md): Fixes for missing B2B prices, widgets not loading and checkout errors
- [General FAQs](https://docs.sparklayer.io/help/faqs.md): Platforms, cost, setup time and whether you need a developer

## Where we're based

Our head office is in Bath, England, and our team is based nearby. Read more in [our story](https://www.sparklayer.io/our-story/index.html).

Wherever you are, see [Response times](#response-times) for when to expect a reply.


---

# Troubleshooting

URL: https://docs.sparklayer.io/help/troubleshooting

Fix common SparkLayer problems by symptom: missing B2B prices, widgets not loading, price list and sync errors, checkout errors, wrong tax and missing orders.

> **Quick summary**
>
> - Start with a diagnostic: pick what's going wrong, answer a few questions and it takes you to the fix, with your answers ready to send us if you're still stuck. Or find your symptom below and work through the checks in order. Most problems come from a missing `b2b` tag, a missing or duplicate SKU, a product left out of the SparkLayer sales channel, or an incomplete customer address.
> - The checks are written for Shopify stores. On other platforms, the screens and some causes differ. See your platform's guide and limitations in [Platforms](https://docs.sparklayer.io/help/platforms.md).
> - To see whether a product has reached SparkLayer, use **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app. Customer sync errors show as a banner on **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app. Can't find a screen at all? See [Finding your way in the app](#finding-your-way-in-the-app).
> - Has something stopped working for every customer at once? Check [SparkLayer's status page](https://status.sparklayer.io/) for an incident first.
> - Want to change how a widget looks or works? See [What you can and can't change](https://docs.sparklayer.io/help/storefront/what-you-can-change.md). Still stuck? [Contact support](https://docs.sparklayer.io/help/support.md), and see the [Pricing FAQs](https://docs.sparklayer.io/help/pricing/faqs.md) for more on pricing.

## Find the fix

Pick what's going wrong. Each diagnostic asks one question at a time and ends with the fix, and where to make it.

## Check these first

Most problems are fixed by one of these:

- **SparkLayer is running normally.** If nothing works for any customer, check [the status page](https://status.sparklayer.io/) for an incident.
- **The customer is a B2B customer.** In Shopify, they have the `b2b` tag, plus the tag of any other [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md) they belong to.
- **The customer's addresses are complete.** Every address in their address book has a country, first line, city and postcode or ZIP code.
- **The product can sync.** It has a unique SKU on every variant, its status is Active, and it's included in the SparkLayer Wholesale sales channel.
- **The customer has prices.** Their customer group has a price list that includes the product.
- **The storefront is set up.** The [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) are installed on the theme you're testing.

## Finding your way in the app

**A guide mentions a screen you can't find**

Check [Where things moved](https://docs.sparklayer.io/help/dashboard.md#where-things-moved) for the full list. Some screens were renamed or moved in the new app. For example, **Activity** is now **Orders** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/activity)), or **SparkLayer Wholesale > Orders** in the Shopify app, **Settings > General** is now **Settings > Configurations** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/settings/general)), or **SparkLayer Wholesale > Settings > Configurations** in the Shopify app, and **Settings > Frontend widgets** is now **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app.

**You can't see Forms in the Shopify app**

**Shopify only:**

Sign in to the SparkLayer Dashboard at [app.sparklayer.io](https://app.sparklayer.io/) and go to **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)). Forms and Data tables are only in the Dashboard. Everything else is in both versions. See [Three versions of the same app](https://docs.sparklayer.io/help/dashboard.md#two-versions).

**You can't find Setup or Try it out in the SparkLayer Dashboard**

Open Setup with **Open Setup** on Home. Open Try it out with **Place a test order** on **Orders** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/activity)), or **SparkLayer Wholesale > Orders** in the Shopify app, which shows until your first order. Neither has a sidebar item in the SparkLayer Dashboard. In the Shopify app, both are in the menu.

**A feature shows a plan name and Unlock instead of a switch**

Click **Unlock** to see what the feature does and start a 14-day free trial. Your plan doesn't include it: for example, **Quotes** need Pro (or the Quoting Engine add-on) and **Invoices** need Growth. See [Unlock a feature](https://docs.sparklayer.io/help/dashboard/plan-and-features.md#unlock-a-feature).

**Sales agents opens a window instead of the screen**

Start the free trial it offers. Sales agents start on the Starter plan, so on Basic, **Sales agents** opens a window that shows what they do instead. See [Sales rep setup](https://docs.sparklayer.io/help/sales-reps.md#plans-and-limits).

**There's no switch to connect a partner app in the Shopify app**

**Shopify only:**

Connect the app from **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app in the [SparkLayer Dashboard](https://app.sparklayer.io/). Partner apps, such as Xero or Cin7 Core, can't be switched on inside Shopify. In the Shopify app, each one has a **Setup guide** button instead. See [Managing integrations](https://docs.sparklayer.io/help/integrations/managing-integrations.md#connect-or-disconnect-a-partner-app).

## Storefront

**Diagnose: SparkLayer not showing or looking wrong?** Find out whether it’s the customer, your theme or the launch step.

1. **What’s happening?** Pick the closest match.
   - SparkLayer isn’t showing at all: go to question 2
   - There’s a “preview mode” banner on my store: go to fix A (Finish the last launch step)
   - It looks broken, doubled up or unstyled: go to question 3
   - Prices or buttons are missing on some products: go to fix B (This is usually the product, not your theme)
2. **Is it happening for every B2B customer, or just one?** Sign in as another B2B customer to compare, or use Place a test order, which opens your store as a test B2B customer. Where to look: Orders > Place a test order (SparkLayer).
   - Every B2B customer: go to question 4
   - Just one customer: go to question 5
3. **What looks wrong?** Sign in as a B2B customer and compare with a retail visitor.
   - Two carts or two account icons: go to fix C (Your theme’s own cart is still showing)
   - Colours or styles stopped working after publishing a theme: go to fix D (Check SparkLayer isn’t loaded twice)
   - Retail elements show to B2B customers: go to fix E (Hide the retail element for B2B customers)
   - The cart count in my header is wrong: go to fix F (The SparkLayer cart is separate from your theme’s cart)
   - A button or feature is missing, such as shopping lists: go to fix G (Your theme may have an older version of SparkLayer)
   - It broke after a theme change: go to fix H (Add SparkLayer to your new theme)
   - Something else: go to fix I (We’ll need to look at your theme)
4. **Have you changed, updated or duplicated your live theme recently?** SparkLayer is added to a theme, so a new or updated theme won’t include it until it’s added there too. Where to look: Online Store > Themes (Shopify admin).
   - Yes: go to fix H (Add SparkLayer to your new theme)
   - No: go to question 6
5. **Are you checking while signed in as that customer?** SparkLayer only appears once a B2B customer signs in. Retail and signed-out visitors see your store as normal.
   - Yes: go to question 7
   - No / not sure: go to fix J (Sign in as the customer first)
6. **Does Theme setup show SparkLayer’s required blocks turned on for your live theme?** Theme setup checks the app blocks on your theme and lets you turn on any that are off. Where to look: Home > Setup > Theme setup (SparkLayer).
   - Yes: go to question 8
   - No / not sure: go to fix K (Turn on SparkLayer’s blocks)
7. **Does the customer have the `b2b` tag?** Check the spelling exactly, with no extra spaces or characters. Where to look: Customers > select the customer > Tags (Shopify admin).
   - Yes: go to question 9
   - No: go to fix L (Add the `b2b` tag)
8. **Did it stop suddenly, for everyone, without any change on your side?** For example, B2B customers are signed out straight after signing in, or see a blank page.
   - Yes: go to fix M (This may be on our side)
   - No: go to fix I (We’ll need to look at your theme)
9. **Are they signing in with the same email as that customer record?** Signing in with a different or mistyped email creates a new retail customer without the tag.
   - Yes: go to fix N (Check the customer has synced)
   - No / not sure: go to fix O (Sign in with the email on the customer record)

**Fixes**

- **A. Finish the last launch step** The banner means SparkLayer is still in preview. In your Shopify admin, open SparkLayer Wholesale under Sales channels and click Start taking B2B orders. If the button isn’t there, a setup step such as adding SparkLayer to your theme isn’t complete yet. Finish it, or ask us to check: we may ask for collaborator access with the Apps and channels permission. Where: Sales channels > SparkLayer Wholesale (Shopify admin). See [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md).
- **B. This is usually the product, not your theme** When SparkLayer shows but some products have no price or buttons, the cause is usually the product’s SKU, sales channel or price list. Next: Product missing, no B2B price or “Unavailable”?
- **C. Your theme’s own cart is still showing** SparkLayer replaces the cart and account links for signed-in B2B customers. If both show, your theme’s header hasn’t been set up for SparkLayer, which is common after a theme update. Send us the theme name and we’ll fix it.
- **D. Check SparkLayer isn’t loaded twice** If SparkLayer is added by the app embed and also by a copy of its script in the theme code, the second copy can override your styles. Keep the app embed and remove the hard-coded script. CSS variables start with two hyphens, for example `--spark-button-color`. Where: Online Store > Themes (Shopify admin). See [Customise the design](https://docs.sparklayer.io/help/storefront/customising-design.md).
- **E. Hide the retail element for B2B customers** Theme or app elements meant for retail shoppers need hiding when a B2B customer signs in, usually after adding a new app or section. Send us a screenshot and the page link and we’ll hide it, or hide it yourself with B2B-only content. See [B2B-only content](https://docs.sparklayer.io/help/platforms/shopify/customisations/b2b-only-content.md).
- **F. The SparkLayer cart is separate from your theme’s cart** Your header’s cart count reads Shopify’s cart, so for B2B customers it shows 0 or items added before they signed in. Hide the count for B2B customers, or have a developer keep it in step with SparkLayer’s cart using the JavaScript SDK. We can hide it for you. See [JavaScript SDK: cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md).
- **G. Your theme may have an older version of SparkLayer** Newer features need a recent version of SparkLayer’s storefront code on your theme. Tell us which feature is missing and the theme name, and we’ll update it.
- **H. Add SparkLayer to your new theme** Your new or updated theme doesn’t include SparkLayer yet. Turn on its blocks in Theme setup, or ask us to install it for you, free. Ideally do this before you publish the theme, so B2B customers aren’t affected. Where: Home > Setup > Theme setup (SparkLayer). See [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md).
- **I. We’ll need to look at your theme** Your setup looks right, so we'll take it from here. Send us your answers with a link to your store and the theme name.
- **J. Sign in as the customer first** SparkLayer only appears for signed-in B2B customers. Sign in as them, or use Place a test order to open your store as a test B2B customer, and check again. Where: Orders > Place a test order (SparkLayer).
- **K. Turn on SparkLayer’s blocks** Without them SparkLayer can’t load for anyone. Turn on any required block that’s off. If one won’t turn on, ask us to install SparkLayer on your theme, free. Where: Home > Setup > Theme setup (SparkLayer). See [Ask our team to install it](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md#get-our-team-to-install-it).
- **L. Add the `b2b` tag** Without it the customer shops as retail and sees none of SparkLayer. Add the tag, save, then ask them to sign out and back in. Where: Customers > select the customer > Tags (Shopify admin).
- **M. This may be on our side** If nothing changed on your store, ask your customers to sign out and back in (clearing cookies helps), then tell us straight away. A sync error on one customer never signs out everyone.
- **N. Check the customer has synced** Their tag is right, so check SparkLayer has their record. Click Show errors on the sync banner. A missing or incomplete address stops a customer syncing: every address in their Shopify address book needs a country, city, address line 1 and postcode. An “Invalid customer group” error means a tag doesn’t match any customer group. Where: Customers (SparkLayer). See [Fix customers that won’t sync](https://docs.sparklayer.io/help/guides/fix-sync-problems.md).
- **O. Sign in with the email on the customer record** A different or mistyped email creates a separate retail customer with no tags. Sign in with the exact email that has the `b2b` tag. You can delete the extra customer in Shopify. Where: Customers > select the customer > Tags (Shopify admin).

**Diagnose: Product missing, no B2B price or “Unavailable”?** Find out whether it’s the product, the price list or your theme.

1. **What’s happening?** Sign in as a B2B customer, then pick the closest match.
   - The product says “Unavailable”, or shows the retail price: go to question 2
   - The product is missing completely: go to question 3
   - The product shows, but SparkLayer’s buttons or price are missing: go to question 4
2. **Search for the SKU in the Price editor. Does it find the product?** “No product was found for SKU” means SparkLayer doesn’t have it. Where to look: Pricing > Price editor (SparkLayer).
   - Yes: go to question 5
   - No product was found: go to question 3
3. **Does every variant of the product have a SKU?** Check each variant, not just the product. A barcode doesn’t count as a SKU. Where to look: Products > select the product (Shopify admin).
   - Yes: go to question 6
   - No: go to fix A (Add a SKU to every variant)
4. **Are SparkLayer’s buttons missing on every product, or just some?** Check a few products while signed in as a B2B customer.
   - Every product: go to fix B (This looks like a tags or theme issue)
   - Just some: go to question 7
5. **Does the product have a price in a price list on the customer’s group?** Without a B2B price, a product shows as Unavailable, or at your store’s own price. Where to look: Pricing > Price editor (SparkLayer).
   - Yes: go to question 8
   - No: go to question 9
6. **Is each SKU unique across your store?** If two variants share a SKU, SparkLayer can’t tell them apart. Where to look: Products (Shopify admin).
   - Yes: go to question 10
   - No / not sure: go to fix C (Make each SKU unique)
7. **Where are they missing?** Product pages and collection pages use different parts of your theme.
   - On the product page: go to question 11
   - On collection or search results pages: go to question 12
   - In a wishlist, quick view or other app: go to fix D (Other apps show your retail price)
8. **Is the customer trying to add fewer than the lowest tier in a tiered price list?** With tiered pricing, the lowest tier also sets the smallest quantity a customer can buy.
   - Yes: go to fix E (Add a tier for smaller quantities)
   - No: go to question 13
9. **Which type of price list should give it a price?** Manual lists are uploaded by CSV or set in the Price editor. Automatic lists work prices out from a pricing source, such as your Shopify prices. Where to look: Pricing > Price lists (SparkLayer).
   - Automatic: go to question 14
   - Manual (CSV): go to question 15
10. **Is the product’s status Active?** SparkLayer only imports active products, not Draft ones. Where to look: Products > select the product (Shopify admin).
   - Yes: go to question 16
   - No: go to fix F (Set the product to Active)
11. **Does this product use a different product template from the ones that work?** Check the Theme template setting on the product. Each template needs SparkLayer’s product widget. Where to look: Products > select the product (Shopify admin).
   - Yes: go to fix G (Add SparkLayer to this product template)
   - No / not sure: go to question 2
12. **Are you using a filter or search app on that page?** Filter and search apps often use their own product card, which needs SparkLayer added separately.
   - Yes: go to fix H (Add SparkLayer to the app’s product card)
   - No / not sure: go to fix I (Add SparkLayer to your product card)
13. **Does the variant’s `sparklayer.settings` metafield set `"sell": false` for this group?** That makes a variant visible but un-sellable on purpose. Where to look: Products > select a variant > Metafields (Shopify admin).
   - Yes: go to fix J (The variant is set not to be sold)
   - No / no metafield: go to fix K (Everything checks out)
14. **Does this variant have a value in the list’s pricing source?** For example, a list based on compare-at price needs a compare-at price on every variant. An empty field means there’s no B2B price. Where to look: Products > select the product (Shopify admin).
   - Yes: go to fix K (Everything checks out)
   - No: go to fix L (Fill in the pricing source)
15. **Did the SKUs change in Shopify after you uploaded the list?** Prices are matched by SKU, so a renamed SKU no longer matches its old row.
   - Yes: go to fix M (Update the price list with the new SKUs)
   - No / not sure: go to question 17
16. **Is the product published to the SparkLayer Wholesale sales channel?** Open the product and check its sales channels. Products from Shopify’s own Bundles app can’t be added to it. Where to look: Products > select the product (Shopify admin).
   - Yes: go to question 18
   - No: go to fix N (Add the product to the SparkLayer Wholesale sales channel)
   - I can’t select it (a bundle): go to fix O (Shopify’s own Bundles app isn’t supported)
17. **Do the SKUs in your CSV match Shopify exactly, with no spaces before or after?** Spreadsheet exports often add spaces. The upload succeeds, but nothing matches.
   - Yes: go to fix P (Add a price for this product)
   - No / not sure: go to fix Q (Trim the SKUs and upload again)
18. **Could the product be hidden on purpose, by B2B Catalogs or a visibility setting?** For example a `b2c-only` tag, or `"display": false` for the customer’s group.
   - Yes / not sure: go to fix R (Check what’s hiding it)
   - No: go to fix K (Everything checks out)

**Fixes**

- **A. Add a SKU to every variant** SparkLayer matches B2B prices to SKUs, so variants without one won’t show. Add a SKU and the product will appear after it syncs. Where: Products > select the product (Shopify admin).
- **B. This looks like a tags or theme issue** When SparkLayer’s buttons are missing on every product, the cause is usually the customer’s tags or your theme. Next: SparkLayer not showing or looking wrong?
- **C. Make each SKU unique** Rename duplicate SKUs so every variant has its own. Then update any price lists that use the old SKUs. Where: Products (Shopify admin).
- **D. Other apps show your retail price** Wishlist, quick view and search apps show Shopify’s own price and don’t know about B2B prices. A SparkLayer widget can be added to the app’s template instead. Ask us, or see the guide. See [Prices in other apps](https://docs.sparklayer.io/help/pricing/pricing-display.md).
- **E. Add a tier for smaller quantities** If the first tier starts at, say, 50, customers can’t buy fewer than 50. Add a price for a quantity of 1 if smaller orders should be allowed. Where: Pricing > Price editor (SparkLayer). See [Quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md).
- **F. Set the product to Active** Draft products don’t sync to SparkLayer. Set it to Active and allow a few minutes for it to sync. Where: Products > select the product (Shopify admin).
- **G. Add SparkLayer to this product template** Each product template needs SparkLayer’s product widget. Switch the product to your main template, or send us the template name and we’ll add it. Where: Products > select the product (Shopify admin).
- **H. Add SparkLayer to the app’s product card** Tell us which filter or search app you use and we’ll add SparkLayer’s product card widget to it.
- **I. Add SparkLayer to your product card** Your theme’s product card is missing SparkLayer’s widget, which often happens after a theme update. Send us a link to the page and we’ll add it.
- **J. The variant is set not to be sold** Remove `"sell": false` for this group, or change it to true, if customers in it should be able to buy it. Where: Products > select a variant > Metafields (Shopify admin). See [Product settings](https://docs.sparklayer.io/help/storefront/product-settings.md).
- **K. Everything checks out** Your setup looks right, so we'll take it from here. Send us your answers with the product link and the customer’s email.
- **L. Fill in the pricing source** The automatic list has nothing to calculate from, so the variant has no B2B price. Add the value, for example a compare-at price, and allow a few minutes for it to sync. Where: Products > select the product (Shopify admin). See [Automatic price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md).
- **M. Update the price list with the new SKUs** Rows for the old SKUs don’t match anything now. Upload the prices again with the new SKUs, or set them in the Price editor. Where: Pricing > Price lists (SparkLayer).
- **N. Add the product to the SparkLayer Wholesale sales channel** SparkLayer only imports products published to its sales channel. Where: Products > select the product (Shopify admin).
- **O. Shopify’s own Bundles app isn’t supported** Its bundle products can’t be published to the SparkLayer sales channel, so they get no B2B price or buttons. Use a bundle app that creates a regular product with its own SKU. See [Bundles and SparkLayer](https://docs.sparklayer.io/help/platforms/shopify/faqs.md#do-bundles-from-other-apps-get-b2b-prices).
- **P. Add a price for this product** Add the SKU to a price list on the customer’s group, or set it in the Price editor. If you don’t want B2B customers to buy it, hide it from them instead. Where: Pricing > Price editor (SparkLayer).
- **Q. Trim the SKUs and upload again** Clear the price list, remove spaces from the SKU column, save the CSV and upload it again. SKUs must match Shopify exactly. Where: Pricing > Price lists (SparkLayer). See [Upload prices by CSV](https://docs.sparklayer.io/help/pricing/csv-upload.md).
- **R. Check what’s hiding it** B2B Catalogs tags and the visibility metafield can hide products on purpose. Next: Product showing to the wrong customers?

**Diagnose: Product showing to the wrong customers?** Check which tool should hide it.

1. **What’s happening?** Pick the closest match.
   - A product shows to customers who shouldn’t see it: go to question 2
   - A product is hidden from customers who should see it: go to fix A (Check the product itself)
2. **Where do they see it?** SparkLayer’s own views and your theme’s pages are hidden by different tools.
   - In SparkLayer’s quick order, search or cart: go to question 3
   - On collection, product or search pages: go to question 4
   - In a section such as a featured collection: go to question 5
3. **Does the variant’s `sparklayer.settings` metafield set `"display": false` for the customer’s group?** Use the group’s handle, for example `base`. Entries for a group override the `base` entry. Where to look: Products > select a variant > Metafields (Shopify admin).
   - Yes: go to question 6
   - No: go to fix B (Add a rule for that group)
4. **Is the free B2B Catalogs app installed and enabled on your live theme?** The visibility metafield only hides products inside SparkLayer. Hiding them from your theme’s pages needs B2B Catalogs. Where to look: Online Store > Themes (Shopify admin).
   - Yes: go to question 7
   - No / not sure: go to fix C (Install B2B Catalogs and enable it on your live theme)
5. **Is the free B2B Catalogs app installed and enabled on your live theme?** Sections such as featured collections are your theme’s, so only B2B Catalogs can hide products in them. Where to look: Online Store > Themes (Shopify admin).
   - Yes: go to fix D (Turn B2B Catalogs off and on again on your live theme)
   - No / not sure: go to fix C (Install B2B Catalogs and enable it on your live theme)
6. **Is the JSON written with straight quotes and valid formatting?** Curly quotes from a word processor, or a missing comma or bracket, break every rule in the value. Paste it into a JSON checker if unsure.
   - Yes: go to fix E (Everything checks out)
   - No / not sure: go to fix F (Fix the JSON)
7. **Is the product tagged, for example `b2b-only`, or in a catalog for the right groups?** `b2b-only` hides a product from retail shoppers. `b2c-only` hides it from B2B customers. Where to look: Products > select the product (Shopify admin).
   - Yes: go to fix D (Turn B2B Catalogs off and on again on your live theme)
   - No: go to fix G (Tag the product)

**Fixes**

- **A. Check the product itself** A product that should show but doesn’t usually has a SKU, status, sales channel or price list issue. Next: Product missing, no B2B price or “Unavailable”?
- **B. Add a rule for that group** Add an entry for the customer’s group with `"display": false` to the variant’s `sparklayer.settings` metafield. To hide it from every B2B customer, use the `base` group. Where: Products > select a variant > Metafields (Shopify admin). See [Product settings](https://docs.sparklayer.io/help/storefront/product-settings.md).
- **C. Install B2B Catalogs and enable it on your live theme** Without it, tags such as `b2b-only` and the visibility metafield can’t hide products on your theme’s pages. Install the free app, then enable it on your live (published) theme. See [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md).
- **D. Turn B2B Catalogs off and on again on your live theme** After app updates or theme changes, the live theme may not have the latest B2B Catalogs code. Turn it off and on again on the live theme. If the product still shows in a section, send us the page link. See [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md).
- **E. Everything checks out** Your setup looks right, so we'll take it from here. Send us your answers with the product link and the customer’s email.
- **F. Fix the JSON** Retype the quotes as straight quotes, correct the formatting and save. Copy an example from Product settings as a starting point. See [Product settings examples](https://docs.sparklayer.io/help/storefront/product-settings.md).
- **G. Tag the product** Add `b2b-only` to keep it from retail shoppers, or set up a catalog for the groups that should see it. Where: Products > select the product (Shopify admin). See [Catalogs per customer group](https://docs.sparklayer.io/help/storefront/b2b-catalogs/configuring-advanced-catalogs.md).

**Diagnose: Stock labels or numbers looking wrong?** Find which setting controls what B2B customers see.

1. **What’s happening?** Sign in as a B2B customer, then pick the closest match.
   - A stock label still shows after I turned stock display off: go to question 2
   - The stock number differs from Shopify: go to question 3
   - It says pre-order or back-order, but there’s stock: go to fix A (Units committed to orders aren’t available)
   - No stock messages show at all: go to question 4
2. **Which label is still showing?** Each label is controlled separately.
   - Pre-order: go to fix B (Tick “Hide pre-order” on the group)
   - In stock, low stock or out of stock: go to question 5
   - Unavailable: go to fix C (“Unavailable” usually means no B2B price)
3. **Does the product show the same number in Product data lookup?** Product data lookup shows the stock SparkLayer has for the product. Where to look: Pricing > Products (SparkLayer).
   - Yes, it matches the storefront: go to fix A (Units committed to orders aren’t available)
   - No, it’s different: go to fix D (Wait for the product to sync)
4. **Is “Show stock availability to customers” ticked on the customer’s group?** It’s in the group’s stock display settings. Where to look: Customers > Groups (SparkLayer).
   - Yes: go to fix E (Your theme needs the stock display setting)
   - No: go to fix F (Turn on stock display for the group)
5. **Is the label in SparkLayer’s product area, or somewhere else on the page?** Your theme can show its own stock label, which SparkLayer’s settings don’t control.
   - In SparkLayer’s area: go to fix G (Check the customer’s group)
   - Somewhere else: go to fix H (That label is your theme’s)

**Fixes**

- **A. Units committed to orders aren’t available** SparkLayer shows Shopify’s Available quantity: on hand minus units committed to open orders. With 1 on hand committed to an order, 0 is available, so if the variant can be sold when out of stock it shows as pre-order. See [How the stock status is chosen](https://docs.sparklayer.io/help/storefront/stock-display.md).
- **B. Tick “Hide pre-order” on the group** Unticking “Show stock availability to customers” hides the in stock, low stock and out of stock labels only. The pre-order label has its own setting. Changes to a group apply straight away. Where: Customers > Groups (SparkLayer). See [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md).
- **C. “Unavailable” usually means no B2B price** It’s usually a price list issue, not a stock one. Next: Product missing, no B2B price or “Unavailable”?
- **D. Wait for the product to sync** SparkLayer’s stock is out of date for this product. Products refresh every 10 minutes, so check again after the next sync. If it stays wrong, check stock locations on the customer’s group and any reserved stock, then contact us. Where: Pricing > Products (SparkLayer).
- **E. Your theme needs the stock display setting** Stock messages also need SparkLayer’s theme configuration to include stock display. Tell us the theme name and we’ll add it.
- **F. Turn on stock display for the group** Tick “Show stock availability to customers” on the customer’s group and save. It applies straight away. Where: Customers > Groups (SparkLayer).
- **G. Check the customer’s group** Stock display is set per customer group, and changes apply straight away. Check you changed the group this customer is in, and that they’re signed in. Where: Customers > Groups (SparkLayer). Next: Wrong prices, payment methods or shipping for a customer?
- **H. That label is your theme’s** SparkLayer’s settings don’t control labels your theme adds. Hide it for B2B customers in your theme, or send us the page link and we’ll help.

**Diagnose: Pack sizes or quantity limits not applying?** Check the metafields behind your product rules.

1. **Are SparkLayer’s metafields turned on in SparkLayer?** SparkLayer doesn’t read metafields until they’re configured in the Metafields card. Where to look: Integrations > Platform (SparkLayer).
   - Yes: go to question 2
   - No / not sure: go to fix A (Turn on SparkLayer’s metafields)
2. **How is the rule set up on the product?** Single metafields, such as `sparklayer.pack_size`, set one rule for everyone. The `sparklayer.settings` metafield sets rules per customer group. Where to look: Products > select a variant > Metafields (Shopify admin).
   - Single metafields: go to question 3
   - The sparklayer.settings metafield: go to question 4
   - Not sure: go to question 3
3. **Does the variant also have a `sparklayer.settings` metafield with a value?** When it does, it takes priority over the single metafields. Where to look: Products > select a variant > Metafields (Shopify admin).
   - Yes: go to fix B (Put the rule inside the settings metafield)
   - No: go to question 5
4. **Does the JSON have an entry for this customer’s group, or a `base` entry?** `base` is the default for every group. An entry for a group overrides it. Use the group’s handle, for example `vip`. Where to look: Customers > Groups (SparkLayer).
   - Yes: go to question 6
   - No: go to fix C (Add an entry for the group)
5. **Is the metafield set on the variant, not the product?** Rules are read per variant, even when a product has only one variant. Where to look: Settings > Custom data > Variants (Shopify admin).
   - Yes, on the variant: go to question 7
   - No, on the product: go to fix D (Move the metafield to the variant)
6. **Is the JSON correctly formatted, with straight quotes?** A missing quote, comma or bracket breaks every rule in the value. Paste it into a JSON checker if unsure.
   - Yes: go to question 8
   - No / not sure: go to fix E (Fix the JSON)
7. **Does the definition’s namespace and key read exactly as documented, such as `sparklayer.pack_size`?** In Shopify the namespace and key are one field. Any other spelling is ignored. Where to look: Settings > Custom data > Variants (Shopify admin).
   - Yes: go to question 9
   - No / not sure: go to fix F (Correct the metafield definition)
8. **Does the rule work on other products, just not this one?** Products on a different theme template may not have SparkLayer’s product widget.
   - Yes: go to fix G (Add SparkLayer to this product’s template)
   - No, it doesn’t work anywhere: go to question 10
9. **Does this variant have a whole number entered?** An empty value means no rule. Where to look: Products > select a variant > Metafields (Shopify admin).
   - Yes: go to question 8
   - No: go to fix H (Add a value to the variant)
10. **Are you testing as a signed-in customer in the group you expect?** Rules follow the customer’s group.
   - Yes: go to fix I (Everything checks out)
   - No / not sure: go to fix J (Check the customer’s group)

**Fixes**

- **A. Turn on SparkLayer’s metafields** In the Metafields card, click Configure and enable the metafields you use. SparkLayer adds their definitions to Shopify for you. Where: Integrations > Platform (SparkLayer). See [Shopify metafields](https://docs.sparklayer.io/help/platforms/shopify/metafields.md).
- **B. Put the rule inside the settings metafield** When a variant has `sparklayer.settings`, its JSON takes priority and the single metafields are ignored. Add the rule, such as `pack_size`, to each group’s entry in the JSON. Where: Products > select a variant > Metafields (Shopify admin). See [Which rule wins](https://docs.sparklayer.io/help/storefront/quantity-rules.md).
- **C. Add an entry for the group** Add an entry with the group’s handle and its rule, or a `base` entry to set a default for everyone. Where: Products > select a variant > Metafields (Shopify admin). See [Product settings](https://docs.sparklayer.io/help/storefront/product-settings.md).
- **D. Move the metafield to the variant** Create the definition under Variants, then add the value to each variant. Where: Settings > Custom data > Variants (Shopify admin).
- **E. Fix the JSON** Correct the formatting and save. Copy an example from Quantity rules as a starting point. See [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md).
- **F. Correct the metafield definition** Use the exact namespace and key from Quantity rules, such as `sparklayer.pack_size` with the Integer type. A definition under another namespace is ignored. Where: Settings > Custom data > Variants (Shopify admin). See [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md).
- **G. Add SparkLayer to this product’s template** The product uses a template without SparkLayer’s product widget, so its rules can’t show. Switch it to your main template, or send us the template name and we’ll add the widget. Where: Products > select the product (Shopify admin).
- **H. Add a value to the variant** Enter a whole number, for example 6, and save. Each variant needs its own value. Where: Products > select a variant > Metafields (Shopify admin).
- **I. Everything checks out** Your setup looks right, so we'll take it from here. Send us your answers with the product link and the customer’s email.
- **J. Check the customer’s group** Rules depend on the customer’s group, so a missing or wrong group tag stops them applying. Next: Wrong prices, payment methods or shipping for a customer?

**Widgets don't appear when a B2B customer signs in**

1. Check the customer has the right tags in Shopify: `b2b` by default, plus the tags for any other customer group rules.
2. Check the customer has a complete address. **Show errors** on the sync banner in **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app lists any customers without one.
3. Check the customer has no sync errors: in **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app, click **Show errors** on the sync banner. An error such as `"code":"resource-id-not-found","message":"Invalid customer group"` means the customer has a tag that doesn't match any of your [customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md) at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app.
4. Check you've installed the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md).
5. Check you're testing on the right Shopify theme. For example, you may have installed SparkLayer on a backup theme.

**Customers can't see B2B prices, or products say "Unavailable"**

These checks are for when the SparkLayer My Account area shows, but product pages have no B2B prices. If nothing from SparkLayer shows, see [Widgets don't appear](#widgets-dont-appear-when-a-b2b-customer-signs-in).

1. Check you've installed the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md).
2. Check the customer has the right tags in Shopify: `b2b` by default, plus the tags for any other [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md) rules.
3. Check the customer has no sync errors: in **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app, click **Show errors** on the sync banner.
4. Check the product has a SKU. To add SKUs in Shopify, edit products one by one, or in bulk with Shopify's **Import** or **Edit products** feature. A bundle from another app needs its own unique SKU too: see [Do bundles from other apps get B2B prices?](https://docs.sparklayer.io/help/platforms/shopify/faqs.md#do-bundles-from-other-apps-get-b2b-prices)
5. Check the product's status is **Active** in your Shopify admin, not **Draft** or **Pending**. SparkLayer only imports active products.
6. Check the product is in both the **Online Store** and **SparkLayer Wholesale** sales channels. SparkLayer only imports pricing for SKUs in its channel, and Shopify only lets customers buy products in Online Store. To add many products at once, go to **Products** ([open in the Shopify admin](https://admin.shopify.com/products)), select them, click **More actions** and choose **Include in sales channels**. If the price list was uploaded before you added them, upload it again.
7. Check you've imported a [price list](https://docs.sparklayer.io/help/pricing.md) that includes the product, and the customer's group uses it. For example, if you have a price list called "Base", check a customer group is assigned that price list. To check a product's prices, search for its SKU in **Pricing > Price editor** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/editor)), or **SparkLayer Wholesale > Pricing > Price editor** in the Shopify app.
8. If you use tiered pricing, check your CSV has a price for a single unit of every product.
9. If the price list is automatic, check the variant has a value in the list's pricing source. An empty field means no B2B price.
10. If you uploaded a CSV, check the SKUs match Shopify exactly, with no spaces before or after, and that no SKUs have changed in Shopify since. See [Why a product shows Unavailable](https://docs.sparklayer.io/help/pricing/managing-pricing.md#unavailable).
11. If only some products are affected, check they use a product template with SparkLayer's product widget.

**Your store shows a "preview mode" banner**

SparkLayer is still in preview until you finish the last launch step. In your Shopify admin, open **SparkLayer Wholesale** under **Sales channels** and click **Start taking B2B orders**. If the button isn't there, a setup step, such as adding SparkLayer to your theme, isn't complete yet. See the [Launch checklist](https://docs.sparklayer.io/help/get-started/launching.md).

**Styles stop working after you publish a theme**

Check SparkLayer isn't loaded twice: once by the app embed and again by a copy of its script in your theme code. The second copy can override your styles. Keep the app embed and remove the hard-coded script. CSS variables start with two hyphens, for example `--spark-button-color`. See [Customise the design](https://docs.sparklayer.io/help/storefront/customising-design.md).

**The cart count in your header is wrong for B2B customers**

SparkLayer's cart is separate from your theme's Shopify cart, so your header's count shows 0, or items added before the customer signed in. Hide the count for B2B customers, or have a developer keep it in step with SparkLayer's cart using the [JavaScript SDK](https://docs.sparklayer.io/developers/javascript-sdk/cart.md). Our team can hide it for you.

**You can't change part of a widget, such as its layout or a button**

Check [What you can and can't change](https://docs.sparklayer.io/help/storefront/what-you-can-change.md). Text, features and colours are settings or CSS, but some parts are fixed: for example, the layout and button order of the product page widget can only be changed with a custom script, and there's no CSS variable for button width.

**A button or feature is missing, such as shopping lists**

Newer features need a recent version of SparkLayer's storefront code on your theme. [Contact us](https://docs.sparklayer.io/help/support.md) with the feature that's missing and the theme name, and we'll update it.

**Prices are different from what you expect**

**On product pages**

1. In **Settings > Taxes and duties** ([open in the Shopify admin](https://admin.shopify.com/settings/taxes)), check whether **Include sales tax in product price and shipping rate** (under **Global settings**) is turned on. SparkLayer always shows prices net (excluding tax).
2. If it's on and you use an [automatic price list](https://docs.sparklayer.io/help/pricing/managing-pricing.md), work out a percentage that takes the tax out too. See [Tax-inclusive prices](https://docs.sparklayer.io/help/pricing/managing-pricing.md#tax-inclusive-prices). For example, if you want a customer to pay 100 GBP in total, they see 83.33 GBP, and 16.67 GBP tax is added at checkout.
3. If the automatic price list uses a different currency from your store's, set a [currency conversion](https://docs.sparklayer.io/help/pricing/managing-pricing.md#set-a-currency-conversion) on the list so SparkLayer converts your Shopify prices at your exchange rate. To set exact prices in another currency, use a manual price list instead.

**In the cart**

1. If **Include sales tax in product price and shipping rate** is on in Shopify, check your automatic price lists allow for tax (as above).
2. If you use a [manual price list](https://docs.sparklayer.io/help/pricing/managing-pricing.md), check you haven't uploaded gross prices (including tax). Upload all prices net (excluding tax), so tax is added correctly in the cart.
3. To tax individual line items instead of the cart's subtotal (the default), [contact our support team](https://docs.sparklayer.io/help/support.md) to turn on line-item tax.

**Tiered pricing doesn't show**

1. Check the `qty` column is filled in correctly in your price list CSV.
2. Check your CSV has a price for a single unit of every product.
3. Check the product is included in the **SparkLayer Wholesale** sales channel in Shopify. SparkLayer only imports pricing for SKUs in that channel.

## Price lists

**The price list import shows errors**

1. Check every product in Shopify has a **unique SKU**.
2. If a product has variants (for example small, medium and large), check none of its SKUs are duplicates.
3. Check the SKU exists in your Shopify catalogue.
4. Check the CSV follows the format in [Pricing](https://docs.sparklayer.io/help/pricing.md), for example with no currency symbols in the **price** column.
5. Check the product is included in the **SparkLayer Wholesale** sales channel in Shopify.
6. Check the product's status is **Active** in Shopify. SparkLayer only imports prices for active products, not drafts.

**A customer gets prices from the wrong price list**

Put the price list you want them to use first on their customer group at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app: when a product is in more than one of the group's price lists, the first list wins. See [Price list order](https://docs.sparklayer.io/help/pricing/managing-pricing.md#price-list-order).

If the order is right, check the customer is in the group you expect, and has no price lists of their own in [Prices for one customer](https://docs.sparklayer.io/help/pricing/customer-pricing.md).

**You can't choose a source for an automatic price list**

Check the products you want B2B customers to buy have SKUs, and that they're included in the **SparkLayer Wholesale** sales channel in Shopify.

An empty **Pricing Source** list usually means SparkLayer can't find SKUs on your store. It needs them to sync product and pricing data.

## Customers, sales agents and applications

**Diagnose: Wrong prices, payment methods or shipping for a customer?** Check the customer’s tags and customer group.

1. **What is the customer seeing?** Pick the closest match.
   - Wrong prices: go to question 2
   - Wrong payment methods: go to question 2
   - Wrong shipping options: go to question 2
2. **Are you checking while signed in as the customer?** B2B prices, payment methods and shipping only apply once a B2B customer signs in.
   - Yes: go to question 3
   - No / not sure: go to fix A (Sign in as the customer first)
3. **Does the customer have the `b2b` tag?** Check the spelling exactly, with no extra spaces or characters. Where to look: Customers > select the customer > Tags (Shopify admin).
   - Yes: go to question 4
   - No: go to fix B (Add the `b2b` tag)
4. **Should they be in a customer group other than Base?** Customers with only the `b2b` tag are in the Base customer group.
   - Yes: go to question 5
   - No, Base is right: go to question 6
5. **Does the customer have that group’s tag, spelt exactly as it is on the group?** Each group shows its Shopify tag. It’s usually `b2b-` followed by the group’s handle, for example `b2b-vip`. Where to look: Customers > Groups (SparkLayer).
   - Yes: go to question 7
   - No: go to fix C (Fix the group tag)
6. **Are the price lists / payment methods / shipping set up on that customer group?** Open the group and check its settings. Where to look: Customers > Groups (SparkLayer).
   - Yes: go to question 8 for prices; fix D (Tags look right: check plan and terms) for payments; fix E (Tags look right: check your shipping setup) for shipping
   - No: go to fix F (Set them up on the group)
7. **Does the customer have only `b2b` and that one group tag?** Look for older group tags left over from a previous setup. A customer can only be in one group. Where to look: Customers > select the customer > Tags (Shopify admin).
   - Yes: go to question 6
   - No, there are others: go to fix G (Remove the extra tags)
8. **Is the product in more than one of the group’s price lists?** SparkLayer uses the first price list on the group that contains the SKU. An automatic list covers every product, so if it’s first it always wins. Where to look: Customers > Groups (SparkLayer).
   - Yes: go to fix H (Put the most specific price list first)
   - No / not sure: go to fix I (Tags look right: check the price itself)

**Fixes**

- **A. Sign in as the customer first** Signed-out visitors see retail prices and checkout. Sign in as the customer, or use Place a test order, and check again. Where: Orders > Place a test order (SparkLayer).
- **B. Add the `b2b` tag** Without it the customer shops as retail, with retail prices and checkout. Add the tag and save. Where: Customers > select the customer > Tags (Shopify admin).
- **C. Fix the group tag** A tag that doesn’t match a group is ignored, and the customer gets Base settings. Copy the tag from the group and add it to the customer. If the group doesn’t exist yet, create it. Where: Customers > Groups (SparkLayer).
- **D. Tags look right: check plan and terms** Some payment methods depend on your plan, and Pay on Account needs the customer’s credit limit and terms set. See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md).
- **E. Tags look right: check your shipping setup** The customer is in the right group, so the cause is in your shipping settings. Next: Shipping not working as expected?
- **F. Set them up on the group** Add the missing price lists / payment methods / shipping to the customer’s group, save, then sign in as the customer to check. Where: Customers > Groups (SparkLayer). See [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md).
- **G. Remove the extra tags** SparkLayer only uses `b2b` and one customer group tag. Extra B2B or group tags can put the customer in the wrong group. Remove the ones you don’t need, save, and ask them to sign out and back in. Where: Customers > select the customer > Tags (Shopify admin).
- **H. Put the most specific price list first** The first list on the group that contains the SKU sets its price. Move your specific lists above any automatic list, and save. Where: Customers > Groups (SparkLayer). See [Price list order](https://docs.sparklayer.io/help/pricing/managing-pricing.md#price-list-order).
- **I. Tags look right: check the price itself** The customer is in the right group, so the difference is coming from the price list or your tax settings. Next: Prices or tax looking wrong?

**Diagnose: Sales agent having problems?** Check their account, role and the customers they can see.

1. **What’s happening?** Pick the closest match.
   - The agent doesn’t see sales agent mode: go to question 2
   - A customer is missing from the agent’s search: go to question 3
   - The agent sees customers they shouldn’t: go to question 4
   - “The cart is being processed by a sales agent”: go to fix A (Another agent has that customer open)
   - The agent can’t edit prices, add customers or override rules: go to question 5
2. **Does the agent’s own customer record have the `b2b` tag?** A sales agent is a B2B customer account with a sales agent role. Where to look: Customers > select the customer > Tags (Shopify admin).
   - Yes: go to question 6
   - No: go to fix B (Add the `b2b` tag to the agent’s account)
3. **Does the missing customer have the `b2b` tag?** Only B2B customers appear in an agent’s search. Where to look: Customers > select the customer > Tags (Shopify admin).
   - Yes: go to question 7
   - No: go to fix C (Add the `b2b` tag to the customer)
4. **Is the agent limited to some customer groups?** By default an agent sees every B2B customer. Where to look: Sales Agents > Agents (SparkLayer).
   - Yes: go to question 8
   - No, all customers: go to fix D (Limit the agent to their customer groups)
5. **Does the agent’s role include permission for this?** Roles decide what an agent can do beyond placing orders, such as editing prices or adding customers. Where to look: Sales Agents > Roles (SparkLayer).
   - Yes: go to question 9
   - No / not sure: go to fix E (Give the role that permission)
6. **Is the person listed as a sales agent in SparkLayer?** Their role decides what they can do. Where to look: Sales Agents > Agents (SparkLayer).
   - Yes: go to question 10
   - No / not sure: go to fix F (Make them a sales agent)
7. **Is the agent limited to some customer groups?** The Sales agents screen shows the groups each agent can see, or All customers. Where to look: Sales Agents > Agents (SparkLayer).
   - Yes: go to question 11
   - No, all customers: go to fix G (Check the customer has synced)
8. **Does your store still use the older sales agent groups metafield (`sparklayer.sales_agent_groups`)?** Older setups gave customers sales agent group values in a metafield. Customer tags never work for this. Where to look: Customers > select the customer > Metafields (Shopify admin).
   - Yes: go to fix H (Check the customers’ sales agent group values)
   - No: go to fix I (Check the customers’ groups)
9. **Is the agent trying to raise a price?** Agents can edit unit prices on an order, but only downwards.
   - Yes: go to fix J (Prices can only be lowered)
   - No: go to fix K (Everything checks out)
10. **Are they signed in on your store with exactly that email?** A different or mistyped email creates a new retail customer with no sales agent role.
   - Yes: go to fix L (Check your plan includes sales agents)
   - No / not sure: go to fix M (Sign in with the sales agent’s email)
11. **Is the customer in one of those groups?** Check the customer’s group tag against the agent’s groups. Where to look: Customers > select the customer > Tags (Shopify admin).
   - Yes: go to fix G (Check the customer has synced)
   - No: go to fix N (Let the agent see that group)

**Fixes**

- **A. Another agent has that customer open** A customer’s cart is locked to the sales agent acting for them. Another agent, or the same login on another device, sees this message until the first agent stops acting for the customer. Give each person their own sales agent login, as shared logins make this much more likely. See [Ordering for a customer](https://docs.sparklayer.io/help/sales-ordering/order-for-a-customer.md).
- **B. Add the `b2b` tag to the agent’s account** Sales agents must be B2B customers in your store before they can be given a sales agent role. Add the tag, then make them a sales agent. Where: Customers > select the customer > Tags (Shopify admin).
- **C. Add the `b2b` tag to the customer** Untagged customers never appear in an agent’s search. Add the tag and save. Where: Customers > select the customer > Tags (Shopify admin).
- **D. Limit the agent to their customer groups** On the agent’s page, tick the customer groups they look after. They then only see customers in those groups. Where: Sales Agents > Agents (SparkLayer). See [Restrict which customers an agent sees](https://docs.sparklayer.io/help/sales-reps.md#restrict-which-customers-a-sales-agent-can-see).
- **E. Give the role that permission** Edit the role, tick the permission and save. It applies straight away to every agent with that role. Where: Sales Agents > Roles (SparkLayer). See [Roles and permissions](https://docs.sparklayer.io/help/sales-reps/roles.md).
- **F. Make them a sales agent** Click Add sales agent, choose the person and give them a role. Where: Sales Agents > Agents (SparkLayer). See [Add a sales agent](https://docs.sparklayer.io/help/sales-reps.md).
- **G. Check the customer has synced** If a tagged customer is in the right group but still missing, they may not have synced. Click Show errors on the sync banner. Where: Customers (SparkLayer).
- **H. Check the customers’ sales agent group values** An agent sees any customer that shares one of their group values. Remove values a customer shouldn’t have. Values can only use letters, numbers and dashes, such as `south-east`, and tags don’t count. Where: Customers > select the customer > Metafields (Shopify admin).
- **I. Check the customers’ groups** The agent sees every customer in the groups ticked for them. Untick groups they shouldn’t see, or move those customers to another group. Where: Sales Agents > Agents (SparkLayer).
- **J. Prices can only be lowered** Agents can lower unit prices on an order, not raise them. To charge more, change the customer’s price list.
- **K. Everything checks out** Your setup looks right, so we'll take it from here. Send us your answers with the agent’s and customer’s email addresses.
- **L. Check your plan includes sales agents** Sales agent ordering is on the Starter plan and above, and extra agents are an add-on. If your plan includes them, send us the agent’s email and we’ll take a look. See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
- **M. Sign in with the sales agent’s email** Ask them to sign out and back in using the exact email that has the sales agent role.
- **N. Let the agent see that group** Tick the customer’s group under the customers this agent can see, or move the customer to one of the agent’s groups. Where: Sales Agents > Agents (SparkLayer).

**Diagnose: Trade applications not working?** Check your form, approvals and customer sign-in.

1. **What’s going wrong?** Pick the closest match.
   - Customers can’t find the application form: go to question 2
   - I’m not told about new applications: go to question 2
   - Approve or Reject on an entry does nothing: go to fix A (Approve and Reject run on workflows)
   - Approved customers can’t see B2B pricing: go to question 2
   - Approved customers didn’t get an email: go to question 2
   - People sign in without applying: go to fix B (Shopify lets anyone create an account)
   - Customers can’t sign in: go to question 3
2. **Which form do you use for applications?** SparkLayer Forms is built into the SparkLayer Dashboard. Customer Fields is a separate Shopify app.
   - SparkLayer Forms: go to question 4 for missing; question 5 for arriving; question 6 for access; question 7 for email
   - Customer Fields: go to question 8 for missing; question 9 for arriving; question 10 for access; question 11 for email
   - Another app: go to fix C (Check your form app’s settings)
3. **Which customer accounts does your Shopify store use?** Shopify has customer accounts (sign in with an emailed code) and legacy accounts (sign in with a password). Where to look: Settings > Customer accounts (Shopify admin).
   - Customer accounts (a code): go to fix D (Sign in with the code, using the right email)
   - Legacy accounts (a password): go to fix E (The customer needs to activate their account)
   - Not sure: go to fix F (Check your customer accounts setting)
4. **Is the form added to a page on your live theme?** Forms are built in SparkLayer, then added to a page on your store. Where to look: Forms (SparkLayer).
   - Yes: go to question 12
   - No / not sure: go to fix G (Add the form to a page)
5. **Do new submissions show on the form’s Entries tab?** Applications appear there as soon as they’re submitted. Where to look: Forms (SparkLayer).
   - Yes: go to fix H (Applications are arriving: add a notification)
   - No: go to question 4
6. **Does approving an application give the customer the `b2b` tag and their group’s tag?** The Wholesale Registration Form template creates the customer with their customer group’s tag when you approve them. Where to look: Forms (SparkLayer).
   - Yes: go to fix I (Approval looks right: check the customer)
   - No / not sure: go to fix J (Check what approval does)
7. **Does the form’s approval workflow send the customer an email?** Emails to customers are sent by a workflow step. Where to look: Forms (SparkLayer).
   - Yes: go to fix K (Check the email arrived)
   - No / not sure: go to fix L (Add an email step to the approval workflow)
8. **Is Customer Fields turned on in your theme, with the form on a page?** The app must be enabled in the theme editor and its form added to a page. Where to look: Online Store > Themes (Shopify admin).
   - Yes: go to question 12
   - No / not sure: go to fix M (Turn on Customer Fields and place the form)
9. **Is “Require account approval” turned on for the form?** With approval on, applications wait in Customer Fields until you approve them.
   - Yes: go to fix N (Check pending customers in Customer Fields)
   - No: go to fix O (Applications go straight to Shopify)
10. **Does the form’s auto-tag rule add `b2b` to approved customers?** Check the rule on the form’s Rules tab.
   - Yes: go to fix I (Approval looks right: check the customer)
   - No / not sure: go to fix P (Add `b2b` in the auto-tag rule)
11. **Is the approval email set up in Customer Fields?** Approval emails for Customer Fields forms are sent by Customer Fields, not SparkLayer.
   - Yes: go to fix K (Check the email arrived)
   - No / not sure: go to fix Q (Set up the approval email in Customer Fields)
12. **Is there a link to the form page in your menu or footer?** Customers need a way to reach the page.
   - Yes: go to fix R (Everything checks out)
   - No: go to fix S (Link to the form from your store)

**Fixes**

- **A. Approve and Reject run on workflows** The buttons, the application status and new-entry emails are run by the form’s workflows, which are on the Growth plan and above. On lower plans the buttons show but do nothing. To approve by hand, create the customer in Shopify with the `b2b` tag and their group’s tag. See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
- **B. Shopify lets anyone create an account** With Shopify’s customer accounts, anyone can sign in with an emailed code. SparkLayer only appears for customers tagged `b2b`, so they see your store as retail. You can redirect them, show a banner pointing to your application form, or sign them out with a message. See [Wholesale-only stores](https://docs.sparklayer.io/help/platforms/shopify/customisations/registration-and-login.md).
- **C. Check your form app’s settings** Make sure approved customers get the `b2b` tag and their group tag. That’s what gives them access to SparkLayer. Next: Wrong prices, payment methods or shipping for a customer?
- **D. Sign in with the code, using the right email** Customers sign in with a code sent to their email, with no password. If they use a different email from their customer record, Shopify creates a new retail customer without their tags. Where: Customers > select the customer > Tags (Shopify admin).
- **E. The customer needs to activate their account** With legacy accounts, a new customer must activate their account from the invite email before they can sign in. Open the customer, click More actions, then Send account invite. Where: Customers > select the customer > Tags (Shopify admin).
- **F. Check your customer accounts setting** Open Settings, then Customer accounts, to see which your store uses. Then start this check again. Where: Settings > Customer accounts (Shopify admin).
- **G. Add the form to a page** Add the form to a page on your live theme, such as a trade account page. Where: Forms (SparkLayer). See [Embed a form](https://docs.sparklayer.io/help/forms/embedding-and-styling.md).
- **H. Applications are arriving: add a notification** To be emailed about new applications, use a workflow with the Form submitted trigger and a Send email step. Workflows are on the Growth plan and above. On lower plans, check the Entries tab. Where: Forms (SparkLayer). See [Workflows](https://docs.sparklayer.io/help/forms/workflows.md).
- **I. Approval looks right: check the customer** If an approved customer still can’t see B2B pricing, check their tags and how they’re signing in. Next: SparkLayer not showing or looking wrong?
- **J. Check what approval does** Set the form’s approval to create the customer with the right customer group. Customers approved before the change need tagging by hand. Where: Forms (SparkLayer). See [Approve trade applications](https://docs.sparklayer.io/help/guides/approve-trade-applications.md).
- **K. Check the email arrived** Ask the customer to check their spam or junk folder, and check the email address on their application.
- **L. Add an email step to the approval workflow** Add a Send email step to the workflow that runs when you approve an application, so customers know they can sign in. Where: Forms (SparkLayer). See [Workflows](https://docs.sparklayer.io/help/forms/workflows.md).
- **M. Turn on Customer Fields and place the form** Enable Customer Fields in your theme editor, then add the form to your registration or wholesale page. Where: Online Store > Themes (Shopify admin).
- **N. Check pending customers in Customer Fields** With approval on, customers are only created in Shopify once you approve them. Review pending applications in the Customer Fields app.
- **O. Applications go straight to Shopify** With approval off, customers are created immediately. Check your Shopify customers list for new accounts. Where: Customers (Shopify admin).
- **P. Add `b2b` in the auto-tag rule** On the form’s Rules tab, make the auto-tag rule add `b2b`, and the group tag if you use one. Customers approved before the change need tagging by hand.
- **Q. Set up the approval email in Customer Fields** Turn on and edit the approved-customer email in the Customer Fields app.
- **R. Everything checks out** Your setup looks right, so we'll take it from here. Send us your answers with a link to the form page.
- **S. Link to the form from your store** Add a link to the form page in your header or footer menu so trade customers can find it.

**A B2B customer can't sign in or sees retail prices**

Work through these in order:

1. **Check their tags in Shopify.** The `b2b` tag must stay on the customer. Any other group tag must match the tag shown under a group's name at **Customers > Groups** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/groups)), or **SparkLayer Wholesale > Customers > Customer groups** in the Shopify app exactly, such as `b2b-trade`. A tag that matches no group shows as an **Invalid customer group** sync error. See [Add customers to a group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md).
2. **Check every saved address is complete.** Each address in their address book, not only the default, needs a country, first line, city and postcode or ZIP code.
3. **Check the email they sign in with.** With Shopify's new customer accounts, anyone can sign in with an emailed code. A different or mistyped email address creates a separate retail account, without the `b2b` tag.
4. **Try a private (incognito) browser window**, to rule out an old session.
5. **Check SparkLayer is on your published theme**, not only on a backup or unpublished copy. See [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md).
6. **If you're testing, use a real Shopify customer** with the `b2b` tag and a complete address, not your staff account.
7. **Still stuck?** [Contact support](https://docs.sparklayer.io/help/support.md) with the customer's email address and the time they tried.

For sync errors, see [Fix customers or products that won't sync](https://docs.sparklayer.io/help/guides/fix-sync-problems.md).

**Customers sign in but land back on your store signed out**

The customer enters their email and code, then lands on your homepage still signed out, often every time they try. It usually works in a private (incognito) window or straight after clearing cookies, then happens again next time. Clearing cookies doesn't fix it for good.

1. **Check your theme's sign-in links.** With Shopify's new customer accounts, your account links need the sign-in route in [Update your theme's sign-in links](https://docs.sparklayer.io/help/platforms/shopify/install.md#set-up-new-customer-accounts). A theme update or redesign can replace them, so check again after any theme change.
2. **Check SparkLayer is on your published theme**, not only on a copy. See [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md).
3. **End the old session.** Ask the customer to go to `www.yourstore.com/account/logout`, then sign in again.
4. **Still stuck?** [Contact support](https://docs.sparklayer.io/help/support.md) with the customer's email address and your theme name. We can update the sign-in links for you.

## Product and customer sync

**Product sync shows errors**

Fix the data in Shopify, usually a missing SKU, then wait for the next partial sync. Products refresh every 10 minutes. Each error message and its fix is in [Fix products](https://docs.sparklayer.io/help/guides/fix-sync-problems.md#fix-products).

**Product data lookup says "No products found"**

**Product data lookup** is in **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app. If it can't find a product by its SKU:

1. Check the product has a valid SKU. To add SKUs in Shopify, edit products one by one, or in bulk with Shopify's **Import** or **Edit products** feature.
2. Check the product's status is **Active** in your Shopify admin, not **Draft** or **Pending**. SparkLayer only imports active products.
3. Check the product is included in the **SparkLayer Wholesale** sales channel. Do this for every product you want B2B customers to see.

If you still can't find it, [contact our support team](https://docs.sparklayer.io/help/support.md).

**Customer sync shows errors**

Fix the listed customer records in Shopify. The rest of your customers have synced. On **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app, the banner reads something like **Customers sync completed with 3 errors**.

1. Click **Show errors** on the banner. **Customer sync errors** lists each customer's name, email and problem.
2. Click **Open customers in Shopify** and fix each customer record. They sync on the next partial sync.

Each error message and its fix is in [Fix customers](https://docs.sparklayer.io/help/guides/fix-sync-problems.md#fix-customers). The most common causes are an incomplete second address and a tag that matches no customer group.

**Customers with a sales agent group won't sync**

**Shopify only:**

Set the sales agent groups metafield to **Limit to preset choices**, with each of your sales agent groups as a choice. If the metafield accepts free text instead, customers who have a value in it can show the sync error "Sales Agent Groups cannot contain other characters than alphanumeric or dashes". Values can only use letters, numbers and dashes, with no spaces. Tags don't put a customer in a sales agent group: only the metafield does.

1. In your Shopify admin, go to **Settings > Custom data** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data)) and click **Customers**.
2. Open the sales agent groups definition (`sparklayer.sales_agent_groups`).
3. Turn on **Limit to preset choices** and add each sales agent group as a choice.
4. Click **Save**. The customers sync on the next partial sync.

See [Set up the sales agent groups metafield](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#set-up-the-sales-agent-groups-metafield).

**A customer isn't in the Customers list**

If you can't find a customer in **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app:

1. Check the customer has the `b2b` tag in Shopify. Only customers tagged `b2b` sync to SparkLayer.
2. Click **Show errors** on the sync banner, if there is one, and check whether the customer is listed with a problem.
3. Check you searched by their name, email or company.

If you still can't find them, [contact our support team](https://docs.sparklayer.io/help/support.md).

## Checkout and orders

**Diagnose: Shipping not working as expected?** Check which shipping your B2B customers use.

1. **Is “Use SparkLayer shipping rates” ticked?** For B2B customers it’s either your Shopify shipping or SparkLayer’s shipping rules, never both. Where to look: Settings > Shipping (SparkLayer).
   - Yes, SparkLayer shipping: go to question 2
   - No, Shopify shipping: go to question 3
2. **What’s wrong?** Pick the closest match.
   - I want live carrier rates: go to fix A (Live rates come from Shopify shipping)
   - Rates should depend on the products: go to fix B (Product-based rates need a shipping app)
   - Free shipping isn’t applied: go to question 4
   - “No shipping methods available” at checkout: go to fix C (Cover the customer’s country and group)
   - I can’t edit my rates after a trial: go to fix D (Ask us to switch them off)
3. **What’s wrong?** Pick the closest match.
   - B2B customers see the same rates as retail: go to fix E (Use a shipping app that sets rates by customer tag)
   - I want to hide free shipping from B2B: go to fix E (Use a shipping app that sets rates by customer tag)
   - B2B customers see wrong or missing rates: go to fix F (Check the customer’s setup)
4. **Is the free shipping a SparkLayer discount?** Free shipping can come from a shipping band or from a discount. Where to look: Pricing > Discounts (SparkLayer).
   - Yes, a discount: go to fix G (Select every shipping method the customer can see)
   - No, a shipping band: go to fix H (Check the band order)

**Fixes**

- **A. Live rates come from Shopify shipping** SparkLayer’s rules charge per band, chosen by order value or weight. For live or calculated carrier rates, untick “Use SparkLayer shipping rates” so B2B customers get your Shopify rates, including shipping apps. Where: Settings > Shipping (SparkLayer). See [Shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md).
- **B. Product-based rates need a shipping app** SparkLayer’s rules work on order value or weight only, not on products or tags. Use Shopify shipping with an app that sets rates by product or customer tag, such as Intuitive Shipping. See [Intuitive Shipping](https://docs.sparklayer.io/help/integrations/customer-experience/intuitive-shipping.md).
- **C. Cover the customer’s country and group** No band matches this customer. Check your shipping rules cover their country, their customer group and the order’s value or weight. Where: Settings > Shipping (SparkLayer).
- **D. Ask us to switch them off** Shipping rules set up during a trial can stay live after a downgrade while the settings are locked. Tell us and we’ll switch SparkLayer shipping off, so your Shopify rates apply.
- **E. Use a shipping app that sets rates by customer tag** Shopify can’t show different rates to different customers on its own. A shipping app that uses customer tags, such as Intuitive Shipping, can. Some apps, including Intuitive Shipping, also need a SparkLayer setting: follow the app’s guide, or tell us which app you use. See [Intuitive Shipping](https://docs.sparklayer.io/help/integrations/customer-experience/intuitive-shipping.md).
- **F. Check the customer’s setup** If one customer sees the wrong rates, check their tags and group. Next: Wrong prices, payment methods or shipping for a customer?
- **G. Select every shipping method the customer can see** A free shipping discount only applies to the shipping methods it names. If you have methods per region, select each one, or make a discount per region. Also check the customer’s group is eligible and the threshold is in their price list’s currency. Where: Pricing > Discounts (SparkLayer). See [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md).
- **H. Check the band order** The first band an order matches sets its cost, so a free band only applies if no band above it also matches. Put the free band first, or make the bands cover separate ranges. Where: Settings > Shipping (SparkLayer). See [Free shipping isn’t applied](https://docs.sparklayer.io/help/ordering/shipping-rules.md#free-shipping-isnt-applied).

**Diagnose: Credit limit or Pay on Account not working?** Check the customer’s credit metafield and group settings.

1. **What’s happening?** Pick the closest match.
   - “Your cart exceeds your available credit limit”: go to question 2
   - Pay on Account doesn’t show at checkout: go to question 3
   - They want to pay part by credit and part by card: go to fix A (One payment method per order)
   - Gift cards don’t work: go to fix B (Gift cards only work at Shopify’s card checkout)
2. **In the customer’s credit metafield, is `balance` what they already owe you?** `balance` is the amount owed, not the credit they have left. Available credit is `credit_limit` minus `balance`. Where to look: Customers > select the customer > Metafields (Shopify admin).
   - Yes: go to question 4
   - No, it’s what they can spend: go to fix C (Set `balance` to what they owe)
3. **Is Pay on Account turned on for the customer’s group?** Payment methods are chosen per customer group. Where to look: Customers > Groups (SparkLayer).
   - Yes: go to fix D (Check the customer’s group)
   - No: go to fix E (Turn on Pay on Account for the group)
4. **Would this order take them over their limit?** For example, with a limit of 250 and a balance of 200, only 50 is available.
   - Yes: go to fix F (The group blocks orders over the limit)
   - No: go to fix G (Everything checks out)

**Fixes**

- **A. One payment method per order** An order can’t be split between Pay on Account and card. The customer can pay the whole order one way.
- **B. Gift cards only work at Shopify’s card checkout** The gift card field is Shopify’s, so it only appears when paying by card. It doesn’t work with Pay on Account, and SparkLayer isn’t a store-credit system.
- **C. Set `balance` to what they owe** To give a customer 250 to spend, use `{"credit_limit":250,"balance":0}`. After a 77.80 order their balance is 77.80, leaving 172.20 available. A balance of 250 means they’ve used it all. Where: Customers > select the customer > Metafields (Shopify admin). See [Credit and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md).
- **D. Check the customer’s group** If the group has Pay on Account but this customer doesn’t see it, check they’re in that group. Next: Wrong prices, payment methods or shipping for a customer?
- **E. Turn on Pay on Account for the group** Add Pay on Account to the group’s payment methods and save. Then set the customer’s credit limit and terms. Where: Customers > Groups (SparkLayer). See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md).
- **F. The group blocks orders over the limit** The customer group is set to block checkout when an order would exceed the limit. Raise the customer’s `credit_limit`, record a payment by lowering their `balance`, or change the group’s credit setting to allow it. Where: Customers > Groups (SparkLayer). See [Block orders over the credit limit](https://docs.sparklayer.io/help/customers/customer-groups.md#block-orders-over-the-credit-limit).
- **G. Everything checks out** Your setup looks right, so we'll take it from here. Send us your answers with the customer’s email and their credit metafield value.

**Diagnose: Quote buttons greyed out?** Check who acts next and what each status allows.

1. **Who can’t act on the quote?** Buyers and merchants see different buttons at each stage.
   - The customer: go to question 2
   - Me or a sales agent: go to question 3
2. **Is the quote’s status “Quote requested”?** That’s the status right after a customer asks for a quote.
   - Yes: go to fix A (You review the quote first)
   - No: go to question 4
3. **Does the person’s role allow them to work on quotes?** Sales agents can only do what their role allows. Where to look: Sales Agents > Roles (SparkLayer).
   - Yes: go to question 5
   - No / not sure: go to fix B (Give the role quote permissions)
4. **Is the customer trying to edit the quote?** Whether a customer can edit a quote is set for each status.
   - Yes: go to fix C (Allow editing for that status)
   - No: go to fix D (Everything checks out)
5. **Are your quote statuses turned on?** Quote statuses and what each allows are set in your configuration. Where to look: Settings > Configurations > Quote statuses (SparkLayer).
   - Yes: go to fix D (Everything checks out)
   - No / not sure: go to fix E (Turn on your quote statuses)

**Fixes**

- **A. You review the quote first** When a customer requests a quote, you or a sales agent review it and adjust prices. Confirm & complete stays greyed out for the customer until you move it on. That’s by design. See [Quoting](https://docs.sparklayer.io/help/ordering/quoting.md).
- **B. Give the role quote permissions** Edit the person’s role, tick the quote permissions and save. Where: Sales Agents > Roles (SparkLayer).
- **C. Allow editing for that status** Open Quote statuses, edit the status the quote is in, and allow the customer to edit it. Where: Settings > Configurations > Quote statuses (SparkLayer).
- **D. Everything checks out** Your setup looks right, so we'll take it from here. Send us your answers with the quote number and who’s trying to act on it.
- **E. Turn on your quote statuses** Enable the quote statuses you use, then reload the quote. Where: Settings > Configurations > Quote statuses (SparkLayer).

**Customers see "An unknown error occurred" at checkout**

The message appears at the top right of the browser. On recent versions of SparkLayer's [Core Script](https://docs.sparklayer.io/help/glossary.md#core-script), it ends with a code, such as **SHOPIFY:002**.

**If there's a code**, find it in the table below.

**If there's no code**, the table can't tell you the cause. Try these first:

1. Refresh the page and try again.
2. Empty the cart, add the products again and check out.
3. In your Shopify admin, look in **Orders > Drafts** ([open in the Shopify admin](https://admin.shopify.com/draft_orders)) for an open draft order for that customer. Delete it, then try again.
4. If several customers see the error at the same time, it may be a wider problem: [contact support](https://docs.sparklayer.io/help/support.md) and we'll check.
5. Check your Core Script version 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. Codes only show on recent versions, so updating it means the next error shows one.

Then check these common causes, with or without a code:

1. Check none of the products in the order have a price of 0.00 in Shopify. SparkLayer relies on the Shopify price being higher than the B2B price to calculate orders correctly. A price of 0.00 causes an error and stops checkout.
2. If you sell in several currencies, check you've set up Shopify Markets, with currencies and shipping methods for each market. See [Shopify Markets and currencies](https://docs.sparklayer.io/help/platforms/shopify/markets-and-currencies.md).
3. If a [sales agent](https://docs.sparklayer.io/help/sales-ordering.md) is placing the order, check the customer's email address is valid. Shopify may reject an invalid email, such as one with a mistyped domain.
4. Ask your developer (or [our support team](https://docs.sparklayer.io/help/support.md)) to check the `siteId` in your [core script](https://docs.sparklayer.io/developers/frontend.md) matches your **Site ID** in [your account](https://docs.sparklayer.io/help/dashboard/account.md#edit-your-account-details). The core script is the code that loads SparkLayer on your store.

If it still happens, [contact support](https://docs.sparklayer.io/help/support.md) with the customer's email address, the time it happened, what was in the cart and a screenshot of the error.

| Error code | What it means |
| --- | --- |
| **SHOPIFY:001** | The customer has a price list in a currency (for example AUD) that isn't enabled in your [Shopify Markets](https://docs.sparklayer.io/help/platforms/shopify/markets-and-currencies.md). In a market with several countries or regions, SparkLayer doesn't support **Show prices to customers in their local currency**: turn it off so B2B customers in that market can place orders. |
| **SHOPIFY:002** | The customer has a price list in a currency (for example AUD), but the shipping country isn't set up in your [Shopify Markets](https://docs.sparklayer.io/help/platforms/shopify/markets-and-currencies.md). |
| **SHOPIFY:003** | There's a problem with product data, such as a variant with no SKU. Try removing the affected product from the order. |
| **SHOPIFY:005** | Shopify's DNS checks are rejecting the order's email address, so it can't check out. Check the email address is valid. |
| **SHOPIFY:006** | The shipping address is in a country that isn't in any of your Shopify Markets. Check every country you ship to belongs to a market. |
| **SHOPIFY:007** | The customer record is missing an email address, shipping phone number or shipping address. All 3 are required for stores using Managed Markets. |
| **PRICING:001** | The customer's group has 2 price lists in different currencies (for example GBP and USD). Change the customer group so it only uses one currency. |

**Customers only see card payment (no Pay by invoice)**

Add **Pay by invoice** (or **Payment on account**) to the customer's group. Customers only see the payment methods their customer group allows, so a group set to **Card at checkout** alone shows card payment (upfront payment) and nothing else.

1. 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 click the customer's group.
2. Override **Payment methods** if it's under **Inherited rules**, then tick **Pay by invoice** or **Payment on account**. To stop card payment for the group, untick **Card at checkout**.
3. Click **Save**.

See [Choose which payment methods a customer group can use](https://docs.sparklayer.io/help/ordering/payment-methods.md#choose-which-payment-methods-a-customer-group-can-use). If the customer belongs to a company, also check **Let them pay later** is on for the company, and **Pay later** for its location. A company or location with pay later off can only pay by card, whatever its group allows. See [Companies](https://docs.sparklayer.io/help/customers/companies.md#paying).

**Customers can't place orders because their addresses are incomplete**

1. Check every address field is filled in on the customer's record in Shopify.
2. Check the customer has no incomplete addresses saved to their account.
3. Check the first line of each address for unusual characters, such as a long dash (―), and replace them with plain text. An address with these may not sync, with no error. This can happen with addresses synced from an ERP.

**No shipping methods show at checkout**

1. If you use SparkLayer's built-in shipping, check your shipping methods in **Settings > Shipping** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/shipping)), or **SparkLayer Wholesale > Settings > Shipping** in the Shopify app: their **Available countries** and **Customer groups**, and their bands. If the customer doesn't match any method, or the order doesn't meet any of a method's bands, no shipping method shows. Look out for bands based on weight. See [Shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md).
2. If you use Shopify's shipping methods, check they include the customer's country. For example, for a customer in the United Kingdom, a shipping method must cover the United Kingdom.
3. If you use Shopify Markets, check you've set up [shipping profiles](https://help.shopify.com/en/manual/shipping/setting-up-and-managing-your-shipping/shipping-profiles) for your destination countries.
4. If you use a shipping app such as [Intuitive Shipping](https://docs.sparklayer.io/help/integrations/customer-experience/intuitive-shipping.md), check its zones include the customer's postcode. In Intuitive Shipping, go to **Activity** and filter by **Unsuccessful** to see which addresses got no rates.

Customers see this as "Sorry, no shipping methods are available for your selected address" at the **Shipping Method** step.

**Shipping costs don't match your shipping rules**

[Contact our support team](https://docs.sparklayer.io/help/support.md). With SparkLayer [shipping](https://docs.sparklayer.io/help/ordering/shipping-rules.md), the prices in the Dashboard should always match the prices customers see at checkout.

**Orders don't show in your Shopify orders**

**Shopify only:**

1. Look in your Shopify draft orders, in **Orders > Drafts** ([open in the Shopify admin](https://admin.shopify.com/draft_orders)). Unless the customer paid with Upfront Payment (by card), the order arrives as a draft order by default. To create completed orders instead, turn on **Auto-complete draft orders** in **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app.
2. Check the order was placed as a B2B customer. You can see this in the order's **Notes** in Shopify.

**Orders show as "Awaiting merchant"**

This is expected: the order is waiting for you. **Awaiting merchant** means the customer has placed the order in SparkLayer, but it isn't a completed order in your store yet. It's usually one of these:

- **A Pay on Account or Pay by Invoice order**, which arrives as a draft order.
- **A Pay Online by Card order the customer didn't finish paying for.** If they leave the Shopify checkout before paying, the order stays a draft with no payment taken. Send them the invoice from the draft, or ask them how they'd like to pay.
- **A Pay Online by Card order placed by a sales agent or company user.** Shopify emails the customer to pay, and the order stays a draft until they do.

On Shopify, find it at **Orders > Drafts** ([open in the Shopify admin](https://admin.shopify.com/draft_orders)), tagged `b2b`. Complete the draft, or turn on **Auto-complete draft orders** at **Integrations > Platform > Shopify order actions** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Shopify order actions** in the Shopify app. If the customer has paid another way, mark the draft as paid to complete it. Shopify doesn't tell you about new draft orders, so [set up an email alert](https://docs.sparklayer.io/help/ordering/automation-and-workflows.md#get-email-alerts-for-new-draft-orders). The customer sees **Awaiting merchant** in [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md#order-statuses) until then. See [Awaiting merchant](https://docs.sparklayer.io/help/glossary.md#awaiting-merchant) and [Process orders in Shopify](https://docs.sparklayer.io/help/guides/process-orders-in-shopify.md).

## Tax

**Diagnose: Prices or tax looking wrong?** Check your Shopify tax settings against your price lists.

1. **What looks wrong?** Pick the closest match.
   - B2B prices are too high, or tax is charged twice: go to question 2
   - Tax is added to shipping in the B2B checkout: go to fix A (Shopify taxes shipping in some regions)
   - I want B2B prices shown including tax: go to fix B (Tax-inclusive display has three parts)
   - VAT or tax is missing at checkout: go to question 3
2. **Is “Include sales tax in product price and shipping rate” turned on?** It’s under Global settings. It decides whether Shopify treats your prices as including tax, which is common for UK, EU and Australian stores. Where to look: Settings > Taxes and duties (Shopify admin).
   - On: go to question 4
   - Off: go to question 5
3. **Is the customer marked as tax exempt in Shopify?** Reverse charge for VAT-registered EU customers uses Shopify’s customer tax exemption. Where to look: Customers > select the customer > Tax settings (Shopify admin).
   - Yes: go to fix C (That’s why tax isn’t added)
   - No: go to fix D (Check the customer’s address and test their checkout)
4. **Which type of price list does the customer use?** Manual lists are uploaded by CSV or set in the Price editor. Automatic lists apply a percentage to your Shopify prices. Where to look: Pricing > Price lists (SparkLayer).
   - Manual (CSV or Price editor): go to question 5
   - Automatic (a percentage): go to question 6
5. **Are the prices in the price list excluding tax (net)?** All SparkLayer prices are net. Tax is added at checkout. Where to look: Pricing > Price editor (SparkLayer).
   - Yes, net: go to fix E (Your tax setup looks right)
   - No, they include tax: go to fix F (Upload your prices excluding tax)
   - Not sure: go to fix G (Compare one product in the Price editor)
6. **Has the list’s percentage been raised to take the tax out too?** An automatic list based on tax-inclusive Shopify prices needs its percentage adjusted for tax. For example, with 20% VAT and a 10% trade discount, use 25% off. Where to look: Pricing > Price lists (SparkLayer).
   - Yes: go to fix E (Your tax setup looks right)
   - No: go to fix H (Adjust the percentage for tax)

**Fixes**

- **A. Shopify taxes shipping in some regions** SparkLayer uses Shopify’s tax calculation. In Canada, the EU, the UK and the US, Shopify charges tax on shipping whatever its “Charge tax on shipping rates” setting says, so the B2B checkout can show tax on shipping. If that’s a problem, use SparkLayer shipping with your rates entered without tax. See [Tax and shipping](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md).
- **B. Tax-inclusive display has three parts** Buyers see gross prices once three things are in place: Tax-inclusive prices turned on for your store (if you don’t see the setting, ask us), the price lists chosen, and a `display_tax_rate` column in the price CSV, for example 10 for Australian GST. It works on manual price lists only, not automatic ones, so use a manual list for those customers. See [Show tax-inclusive prices](https://docs.sparklayer.io/help/pricing/pricing-display.md#show-tax-inclusive-prices).
- **C. That’s why tax isn’t added** Tax-exempt customers check out without tax. Remove the exemption if they should pay it. Where: Customers > select the customer > Tax settings (Shopify admin).
- **D. Check the customer’s address and test their checkout** Tax follows the customer’s default address and your Shopify tax regions. Check their default address, that you collect tax in that country, and that the products are set to charge tax. Then place a test order as the customer. Where: Settings > Taxes and duties (Shopify admin).
- **E. Your tax setup looks right** The SparkLayer checkout shows net prices with tax on its own line. If “Include sales tax” is on, the Shopify order shows tax-inclusive prices instead. The totals are the same: it’s just shown differently.
- **F. Upload your prices excluding tax** Prices that already include tax get tax added again at checkout, so customers pay it twice. Convert them to net prices and upload the list again. Where: Pricing > Price lists (SparkLayer).
- **G. Compare one product in the Price editor** Pick a product, work out its price without tax, and check it matches the Price editor. If it doesn’t, your list includes tax and needs uploading again as net prices. Where: Pricing > Price editor (SparkLayer).
- **H. Adjust the percentage for tax** Without it, the percentage comes off your tax-inclusive Shopify prices, so B2B prices come out too high and tax is added again at checkout. Where: Pricing > Price lists (SparkLayer). See [Adjust automatic price lists for tax](https://docs.sparklayer.io/help/pricing/managing-pricing.md#tax-inclusive-prices).

Each symptom below has its quick check. The full set-up, with net prices, exemptions and tax apps, is in [Get B2B tax and VAT right](https://docs.sparklayer.io/help/guides/tax-and-vat.md).

**Tax shows as zero**

**Shopify only:**

In Shopify, check the customer isn't tax-exempt (**Manage tax exemptions** on the customer), the product has **Charge tax on this product** ticked, and you collect tax in the customer's country (**Regional settings** in **Settings > Taxes and duties** ([open in the Shopify admin](https://admin.shopify.com/settings/taxes))). See [Get B2B tax and VAT right](https://docs.sparklayer.io/help/guides/tax-and-vat.md#make-tax-exempt-customers-exempt).

**Tax is charged when it shouldn't be**

**Shopify only:**

Make the customer tax-exempt: in Shopify, open them, click **Manage tax exemptions** and untick **Collect tax**. If you use a tax app, exempt them there too: see [Tax is charged although you use a tax app](#tax-is-charged-although-you-use-a-tax-app) and [Make tax-exempt customers exempt](https://docs.sparklayer.io/help/guides/tax-and-vat.md#make-tax-exempt-customers-exempt).

**Tax isn't charged when it should be**

**Shopify only:**

The customer is probably tax-exempt: in Shopify, open them, click **Manage tax exemptions** and tick **Collect tax**. If that's not it, check you collect tax in the country of their shipping address. See [Get B2B tax and VAT right](https://docs.sparklayer.io/help/guides/tax-and-vat.md#if-somethings-not-right).

**Order prices are different from the checkout**

**Shopify only:**

Checkout uses the lower of the SparkLayer price and the Shopify price, including tax. Check that automatic price lists based on tax-inclusive Shopify prices allow for tax, and that the SparkLayer price (in **Pricing > Price editor** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/editor)), or **SparkLayer Wholesale > Pricing > Price editor** in the Shopify app) is below the Shopify price. See [Make your price lists net](https://docs.sparklayer.io/help/guides/tax-and-vat.md#make-your-price-lists-net) and [Tax-inclusive prices](https://docs.sparklayer.io/help/pricing/managing-pricing.md#tax-inclusive-prices).

**Tax is wrong when shipping to another country**

**Shopify only:**

Check you collect tax in the delivery country: in **Settings > Taxes and duties** ([open in the Shopify admin](https://admin.shopify.com/settings/taxes)), find it under **Regional settings** and check the **Collecting tax** column. See [Get B2B tax and VAT right](https://docs.sparklayer.io/help/guides/tax-and-vat.md).

**Tax or VAT is charged twice**

Your B2B prices include tax, and SparkLayer adds it again at checkout. Upload manual price lists net (excluding tax), and make automatic price lists based on tax-inclusive Shopify prices take the tax out. See [Make your price lists net](https://docs.sparklayer.io/help/guides/tax-and-vat.md#make-your-price-lists-net).

**You need to charge tax on some products but not others**

**Shopify only:**

[Contact our support team](https://docs.sparklayer.io/help/support.md) to turn on line-item tax, then untick **Charge tax on this product** on the products that shouldn't be taxed. See [Handle products with different tax rates](https://docs.sparklayer.io/help/guides/tax-and-vat.md#handle-products-with-different-tax-rates).

**Tax is charged although you use a tax app**

**Shopify only:**

Exempt the customer in your tax app, such as Avalara or TaxJar, as well as in Shopify: tax apps override Shopify's settings, and the two exemptions work independently. See [Make tax-exempt customers exempt](https://docs.sparklayer.io/help/guides/tax-and-vat.md#make-tax-exempt-customers-exempt), and the [Avalara steps](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md#tax-is-charged-but-i-use-a-third-party-tax-app-eg-avalara-taxjar).


---

# General FAQs

URL: https://docs.sparklayer.io/help/faqs

Answers to common SparkLayer questions: plans and trials, setup, the storefront, B2B customers and prices, payments, shipping, tax, integrations and support.

## About SparkLayer

**What can I do with SparkLayer?**

SparkLayer adds B2B (wholesale) ordering to your existing website, without a new store or a custom-built B2B site. You can:

- Set B2B prices for each group of customers, or for one customer
- Give B2B customers self-service ordering, quick re-ordering and saved shopping lists
- Accept B2B payments, such as Pay on Account and Pay by Invoice, with net terms and credit limits
- Set pack sizes, minimum and maximum quantities, and quantity price breaks
- Let your sales reps place orders for customers with [sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md)
- Manage the quote-to-order process with the [Quoting Engine](https://docs.sparklayer.io/help/ordering/quoting.md)
- Set pre-order and back-order rules

Some features need a paid plan: see [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md) for what's on each one, and [Storefront features](https://docs.sparklayer.io/help/storefront.md) for what your customers see.

**How is SparkLayer different from Shopify's own B2B features?**

Shopify's native B2B covers the basics, such as company accounts, a few pricing catalogs and net terms. SparkLayer adds more on any Shopify plan, including unlimited price lists from the Starter plan, a sales agent portal for your reps, bulk and CSV ordering, shopping lists and the Quoting Engine. It works over your existing theme.

A customer gets one ordering experience or the other, not both at once. See [Shopify FAQs](https://docs.sparklayer.io/help/platforms/shopify/faqs.md) for the full comparison.

**How does SparkLayer compare to other B2B solutions?**

The main difference, beyond features, is that you keep using your existing website. SparkLayer "layers" on top of it (hence the name).

Many other B2B solutions are separate web portals, so customers use an entirely different website. If you already have a website (for example, for your retail customers) or an eCommerce platform you know well, a separate portal means more systems and tools to manage.

Every B2B solution suits particular use cases or customer types. We're happy to talk this through: [book a demo](https://www.sparklayer.io/demo/).

**Can I run my B2C store alongside my B2B store?**

Yes. You can install SparkLayer on your existing retail (B2C) store and run B2C and B2B from the same store. We call this a hybrid setup. Retail customers see your store as normal. When B2B customers sign in, they see SparkLayer's widgets, with their prices and B2B ordering.

**Can retail shoppers see my wholesale prices?**

No. SparkLayer only shows B2B prices to B2B customers who've signed in. Your products and retail prices stay visible to everyone until you hide them.

On Shopify, hide B2B-only products from retail shoppers with the free [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md) app. Hiding prices from signed-out visitors, or making everyone sign in first, is a theme code change for your developer. See [Keep wholesale prices and products hidden from retail shoppers](https://docs.sparklayer.io/help/guides/hide-wholesale-from-retail.md). On other platforms, see your platform's FAQs, linked at the foot of this page.

**Do you have a demo store to test SparkLayer?**

Yes. See [Try our demo](https://docs.sparklayer.io/help/get-started/demo.md).

## Plans, trials and billing

**How much does SparkLayer cost?**

There's a free **Basic** plan (Shopify only) and 4 paid plans: **Starter** ($49 per month), **Growth** ($149), **Pro** ($299) and **Enterprise** (from $499). Plans differ by B2B orders per month, sales agents and features. See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md), or our [pricing page](https://www.sparklayer.io/pricing/) for the latest prices.

On Shopify, you're billed through Shopify, and on Wix through Wix. For other platforms, see [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md).

**Is there a free trial, and what happens when it ends?**

Yes. Every paid plan has a 14-day free trial. When it ends, you're billed for the plan you chose, and everything you set up during the trial stays as it is. To avoid being billed, change plan or cancel before the 14 days are up. See [Free trials](https://docs.sparklayer.io/help/dashboard/billing.md#free-trials).

**What happens if I go over my plan's B2B orders?**

Nothing is blocked. Your customers keep ordering, and your plan card shows **Over limit** and suggests a plan that fits. Only orders placed through SparkLayer count, not retail orders, and cancelled or refunded orders still count. See [What counts as a B2B order](https://docs.sparklayer.io/help/plans-and-features.md#what-counts-as-a-b2b-order).

**Can I downgrade, pause or cancel?**

Yes. To change plan, open the plans window from your plan card (or **Plan** in the Shopify app) and choose another plan. On Shopify, you can move to the free **Basic** plan to stop paying but keep your account and setup. 

To cancel, uninstall SparkLayer from your store. Treat uninstalling as deleting your SparkLayer data, so [contact us](https://docs.sparklayer.io/help/support.md) first. See [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md#cancel), and for refunds, the [Refund policy](https://docs.sparklayer.io/help/policies/refund-policy.md).

**Will you install SparkLayer for me?**

Yes. On every plan, our team installs SparkLayer's storefront widgets on your website for you, free, and tests them. Paid plans also include personalised onboarding sessions. See [Request free installation](https://docs.sparklayer.io/help/support.md#request-free-installation). 

Free installation doesn't include customising your theme, such as restyling the widgets or custom scripts. See [What the free installation covers](https://docs.sparklayer.io/help/storefront/what-you-can-change.md#what-the-free-installation-covers).

**Where do I see my plan and usage?**

In the SparkLayer Dashboard, it's on the plan card at the foot of the sidebar. In the Shopify app, click **Plan** in the menu. Home shows a plan card too. See [Your plan and usage](https://docs.sparklayer.io/help/dashboard/plan-and-features.md).

## Platforms and setup

**Which eCommerce platforms and systems does SparkLayer integrate with?**

SparkLayer works with Shopify (every Shopify plan), BigCommerce (Plus, Pro and Enterprise), Wix (Wix Editor and Wix Studio), WooCommerce (early access) and Magento (Adobe Commerce, on the Enterprise plan). For other platforms and custom-built websites, connect SparkLayer with [SparkLayer Ignite](https://docs.sparklayer.io/ignite.md), our framework for building platform integrations (Enterprise plan), as long as your platform can connect to an external API. See [Compare platforms](https://docs.sparklayer.io/help/platforms/compare.md) for which features work on each platform.

SparkLayer also integrates with ERP, inventory, accounting and shipping apps. See [Integrations](https://docs.sparklayer.io/help/integrations.md).

**How do I install SparkLayer on my store?**

On Shopify and BigCommerce, install our official [Shopify](https://apps.shopify.com/sparklayer) or [BigCommerce](https://www.bigcommerce.com/apps/sparklayer-b2b-wholesale/) app and follow the onboarding steps. For other platforms, see the install guides in [Platforms](https://docs.sparklayer.io/help/platforms.md).

Once your SparkLayer account is created, the 5-step **Setup** checklist takes you from your first price list to SparkLayer showing on your theme. See [Get started](https://docs.sparklayer.io/help/get-started.md).

**How long does SparkLayer take to set up?**

Most stores finish the 5 steps of the **Setup** checklist in under 15 minutes, if you manage your pricing and customers with SparkLayer's built-in tools. Our team can install the storefront widgets for you, free. See [Get started](https://docs.sparklayer.io/help/get-started.md).

Larger integrations take longer. These are usually Enterprise merchants who need back-office connections, such as an ERP. Setup times vary, and we'll work with you on a project plan.

**Do I need to hire a developer to integrate SparkLayer?**

Not to set it up. The **Setup** checklist walks you through it, and our team installs the storefront widgets for you, free.

A developer helps with some jobs, such as [customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md) beyond the settings, hiding prices from signed-out visitors, and connecting an ERP or other system through the [SparkLayer API](https://docs.sparklayer.io/developers/api.md).

## Your storefront

**What can I change about how SparkLayer looks on my store?**

Quite a lot, without code: any wording, features such as shopping lists and favourites, and the order of My Account sections and payment methods are settings at **Storefront > Options** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/storefront/options)), or **SparkLayer Wholesale > Storefront > Options** in the Shopify app. Colours, fonts, sizes and spacing are CSS variables, set in your theme. Your own messages go in [custom slots](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md).

Some parts are fixed: for example, the layout and button order of the product page widget can only be changed with a custom script from your developer. See [What you can and can't change](https://docs.sparklayer.io/help/storefront/what-you-can-change.md).

**Will SparkLayer slow my website down?**

No. The SparkLayer frontend only loads when a B2B customer signs in. For your retail (B2C) customers, no SparkLayer code loads at all.

When a B2B customer signs in, the interfaces load in the background (asynchronously). So, even though SparkLayer is a hosted third-party solution, the effect on page load times is negligible.

**Does SparkLayer work across different devices?**

Yes. SparkLayer works on mobile, tablet and desktop devices.

**Which languages and currencies does SparkLayer support?**

SparkLayer's widgets show in your store's language, from 28 supported languages, and you can change any of their text. See [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md).

For more than one currency, create a price list in each currency and assign it to the customer group that uses it. On Shopify, you need a Shopify Markets market for each currency: see [Markets and currencies](https://docs.sparklayer.io/help/platforms/shopify/markets-and-currencies.md). Wix stores accept a single currency, so orders are created in your store's default currency.

## Customers and pricing

**How do B2B customers sign up or get access?**

You decide who's a B2B customer. Add them to a customer group in your eCommerce platform: on Shopify, tag them `b2b`, plus the group's tag if they're in another group, for example `b2b-trade`. See [Add customers to a group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md).

For new customers to apply, use a registration form, such as the **Wholesale Registration Form** template in [SparkLayer Forms](https://docs.sparklayer.io/help/forms.md), on every plan. Approving an application creates the customer in your store with their customer group. The **Approve** and **Reject** buttons and notification emails run on form workflows, on the Growth plan and above. Without them, you create the customer yourself. See [Approve trade applications](https://docs.sparklayer.io/help/guides/approve-trade-applications.md).

**How do I give different customers different prices?**

With price lists and customer groups. A price list holds your B2B prices, and each [customer group](https://docs.sparklayer.io/help/customers/customer-groups.md) has the price lists its customers see. Every B2B customer is in one group. To give one customer their own prices or an extra discount, use [customer pricing](https://docs.sparklayer.io/help/pricing/customer-pricing.md).

Create price lists 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. Upload prices by CSV, or base them on a rule. Basic includes 3 price lists, and paid plans unlimited. See [Managing pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md) and the [Pricing FAQs](https://docs.sparklayer.io/help/pricing/faqs.md).

**Can I automate B2B pricing, such as a discount off my retail prices?**

Yes. Create an automatic price list based on a rule. For example, on Shopify you can set up a B2B price list that's 20% off your Shopify prices. See [Managing pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md).

**Do I manage my product catalogue in SparkLayer?**

No. You manage your product catalogue and categories in your eCommerce platform. SparkLayer links B2B data, such as prices and pack sizes, to each product's SKU, so every product B2B customers buy needs a unique SKU. It then shows the right information to each customer.

**Can I set minimum order quantities or pack sizes?**

Yes, on every plan. Give a product a pack size (for example, multiples of 6) or a minimum or maximum quantity. For a limit on the whole order, such as a minimum order value, set order limits on a customer group. Wix doesn't support metafields, so product quantity rules aren't available there, but order limits are. See [Quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md).

**Can my sales reps place orders for customers?**

Yes, with [sales agent ordering](https://docs.sparklayer.io/help/sales-ordering.md), on the Starter plan and above. A sales agent signs in to your store, chooses a B2B customer and orders at that customer's prices. Starter includes 1 sales agent, Growth 2 and Pro 5, and you can add more. See [Sales rep setup](https://docs.sparklayer.io/help/sales-reps.md).

On Shopify, don't create a draft order by hand in your Shopify admin instead: it uses your Shopify prices, not the customer's B2B prices.

## Payments, shipping and tax

**Does SparkLayer process payments?**

No. SparkLayer uses the payment methods set up in your eCommerce platform, such as Shopify. As well as paying online by card, you can offer B2B customers Pay on Account or Pay by Invoice, and choose the methods for each customer group. See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md). On Shopify, the interactive guide [How payments work](https://docs.sparklayer.io/help/guides/how-payments-work.md) follows each method from checkout to payment.

**Can I offer net terms or let customers pay on account?**

Yes, on every plan. With **Pay on Account** and **Pay by Invoice**, customers order now and pay you later. Give each customer net terms, such as Net 30, and a credit limit for Pay on Account. You collect the payment your usual way: SparkLayer doesn't take it. See [Credit limits and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md).

On Wix, customers can still pay on account or by invoice, but you can't set a credit limit or net terms: those are stored in metafields, which Wix doesn't support. See [Wix FAQs](https://docs.sparklayer.io/help/platforms/wix/faqs.md).

**How does shipping work for B2B orders?**

By default, B2B customers see your store's own shipping methods at checkout. To give B2B customers their own methods, priced by customer group, order total or weight, use SparkLayer shipping rates, on the Starter plan and above. Customers get one or the other, never both. See [Shipping rules](https://docs.sparklayer.io/help/ordering/shipping-rules.md).

**How does SparkLayer handle tax and VAT?**

SparkLayer shows B2B prices excluding tax (net) by default, and adds tax at the last step of checkout. It doesn't calculate tax itself: it uses your eCommerce platform's tax settings, including tax-exempt customers. See [How tax works at checkout](https://docs.sparklayer.io/help/ordering/tax-and-shipping.md), or follow [Get B2B tax and VAT right](https://docs.sparklayer.io/help/guides/tax-and-vat.md).

## Integrations, API and security

**Does SparkLayer integrate with my ERP or accounting software?**

SparkLayer connects directly to Brightpearl, Cin7 Core, Katana, Linnworks and Unleashed (ERP and inventory), and to Xero and QuickBooks Online (accounting). These need the Pro plan or above, and a Shopify store, except Linnworks, which works on every platform. ERPs send your B2B customers and prices into SparkLayer on a schedule, every 1 to 4 hours depending on the app. See [Integrations](https://docs.sparklayer.io/help/integrations.md).

**Do I need an ERP, PIM, CRM or iPaaS integration to use SparkLayer?**

No. With SparkLayer's import tools, you can set up pricing and customer rules in the SparkLayer Dashboard without a back-office system.

If you do use one, connect it with one of our [ready-made integrations](https://docs.sparklayer.io/help/integrations.md), or with the [SparkLayer API](https://docs.sparklayer.io/developers/api.md). If you use an iPaaS (integration platform as a service), connect that to SparkLayer instead of your ERP.

**Will SparkLayer work with my existing ERP integration?**

It depends on what you need. If your online store is already connected to your ERP, there's a good chance you won't need any more integration work. Orders placed through SparkLayer are created like any other order, so your ERP can import them as usual. SparkLayer also uses the stock levels already in your eCommerce store.

A deeper integration, such as syncing B2B pricing from your ERP, needs its own integration.

**Is there an API?**

Yes. The [SparkLayer API](https://docs.sparklayer.io/developers/api.md) lets you connect systems such as an ERP or CRM, for example to send in prices and customers. It's on the Pro and Enterprise plans.

**How do you keep my data secure?**

Our security, privacy, business continuity and incident management policies are in the [SparkLayer Trust Center](https://www.sparklayer.io/trust/), so it's the place to send anyone doing a security or procurement review. Questions about any policy: email [contact@sparklayer.io](mailto:contact@sparklayer.io). See [Policies](https://docs.sparklayer.io/help/policies.md).

## Using the app

**Do I use the SparkLayer Dashboard or the Shopify app?**

On Shopify, use whichever suits you. Both have the same screens and work on the same account. SparkLayer is in your Shopify admin as **SparkLayer Wholesale**, under **Sales channels**, and you can also sign in to the SparkLayer Dashboard at [app.sparklayer.io](https://app.sparklayer.io/). On other platforms, you use the SparkLayer Dashboard. See [Find your way around SparkLayer](https://docs.sparklayer.io/help/dashboard.md).

**Why can't I see Forms in the Shopify app?**

**Shopify only:**

Sign in to the SparkLayer Dashboard at [app.sparklayer.io](https://app.sparklayer.io/) to build and manage forms. Forms and Data tables are only in the Dashboard, not the Shopify app. See [Forms](https://docs.sparklayer.io/help/forms.md).

**A guide mentions a screen I can't find. Where did it go?**

Check [Where things moved](https://docs.sparklayer.io/help/dashboard.md#where-things-moved). Some screens were renamed or moved in the new app. For example, **Activity** is now **Orders**, **Settings > General** is now **Settings > Configurations**, and **Integrations > Data Sync** is now **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app.

## Getting help

**Something isn't working. Where do I start?**

Start with [Troubleshooting](https://docs.sparklayer.io/help/troubleshooting.md): pick what's going wrong and it takes you to the fix. Most problems come from a missing `b2b` tag, a missing or duplicate SKU, a product left out of the SparkLayer sales channel, or an incomplete customer address. Common ones include [a B2B customer who can't sign in or sees retail prices](https://docs.sparklayer.io/help/troubleshooting.md#b2b-customer-cant-sign-in-or-sees-retail-prices) and ["An unknown error occurred" at checkout](https://docs.sparklayer.io/help/troubleshooting.md#customers-see-an-unknown-error-occurred-at-checkout).

**How do I know if SparkLayer is down?**

Check [status.sparklayer.io](https://status.sparklayer.io/). It shows whether the SparkLayer Dashboard, storefront widgets and APIs are running normally, and any incident we're working on, with updates until it's fixed.

**How do I contact support, and how quickly do you reply?**

Email [support@sparklayer.io](mailto:support@sparklayer.io), or click the message icon in the SparkLayer Dashboard. We reply within 24 hours on weekdays, and within 48–72 hours at weekends. The Enterprise plan adds 24/7 support with a service level agreement (SLA). See [Contact support](https://docs.sparklayer.io/help/support.md).

Our head office is in Bath, England, and our team is based nearby.

## More FAQs

- [Shopify FAQs](https://docs.sparklayer.io/help/platforms/shopify/faqs.md)
- [BigCommerce FAQs](https://docs.sparklayer.io/help/platforms/bigcommerce/faqs.md)
- [Wix FAQs](https://docs.sparklayer.io/help/platforms/wix/faqs.md)
- [WooCommerce FAQs](https://docs.sparklayer.io/help/platforms/woocommerce/faqs.md)
- [Magento FAQs](https://docs.sparklayer.io/help/platforms/magento/faqs.md)
- [Pricing FAQs](https://docs.sparklayer.io/help/pricing/faqs.md)


---

# Glossary

URL: https://docs.sparklayer.io/help/glossary

Plain-English definitions of the SparkLayer terms used in these docs, from customer groups and price lists to sales agents, quotes and net terms.

Plain-English definitions of the terms used in the SparkLayer docs. Each entry links to the guide that covers it.

## The basics

### B2B

Business to business: selling to other businesses, such as retailers, trade customers and distributors, usually at trade (wholesale) prices. SparkLayer adds B2B ordering to your existing store. See [How SparkLayer works](https://docs.sparklayer.io/help/get-started/how-sparklayer-works.md).

### DTC

Direct to consumer: selling to the public at your normal retail prices, also called B2C (business to consumer) or retail. A [hybrid store](#hybrid-store) serves DTC and B2B customers from the same store.

### SKU

Stock keeping unit: the product code on each product and variant in your eCommerce platform. SparkLayer matches B2B prices to products by SKU, so every product needs one, and each must be unique. See [Check your products have unique SKUs](https://docs.sparklayer.io/help/get-started/launching.md#check-your-products-have-unique-skus).

### Tag

A keyword on a customer record in your eCommerce platform's admin (on Wix, a label does the same job). SparkLayer reads tags to know who is a [B2B customer](#b2b-customer) (`b2b`) and which [customer group](#customer-group) they're in (such as `b2b-vip`). See [Assign customers to a customer group](https://docs.sparklayer.io/help/customers/add-customers-to-a-group.md#assign-customers-to-a-customer-group).

### CSV

A spreadsheet file saved as comma-separated values, which most spreadsheet apps can export. You can upload exact B2B prices to a price list as a CSV file. See [Price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md).

### Setup checklist

The **Setup** screen: 5 steps from your first price list to SparkLayer showing on your store's theme, each ticking itself off when it's done. It's **Setup** in the Shopify app's menu, or **Open Setup** on Home in the SparkLayer Dashboard. See [Get started](https://docs.sparklayer.io/help/get-started.md).

### Try it out

A screen where you place a test order on your own store as a B2B buyer would, without inviting anyone. Test orders don't count towards your plan. See [Try it out](https://docs.sparklayer.io/help/get-started/launching.md#place-a-test-order).

## Customers and accounts

### B2B customer

A customer who sees your B2B pricing and ordering rules when they sign in to your store. On Shopify, that's a customer tagged `b2b`. See [Customers](https://docs.sparklayer.io/help/customers.md).

### Customer group

A set of ordering rules shared by a group of B2B customers, such as their price lists, payment methods and order limits. On Shopify, an extra tag such as `b2b-vip` puts a customer in a group, and groups are under **Companies** in the app (**Groups** in the SparkLayer Dashboard's sidebar). See [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md).

### Base customer group

The customer group every SparkLayer account starts with. B2B customers who don't have another group's tag are in it. See [Customer groups](https://docs.sparklayer.io/help/customers/customer-groups.md).

### Company

A business you sell to, such as a shop or distributor, with its own customer group, pricing, payment terms and people. On Shopify, companies are your Shopify B2B companies, kept in sync both ways. See [Companies](https://docs.sparklayer.io/help/customers/companies.md).

### Company location

A branch, store or site of a company. Locations can sit inside each other, as deep as you need, and inherit their company's settings unless you set their own. See [Company locations](https://docs.sparklayer.io/help/customers/company-locations.md).

### Location role

What a person can do at a company location: **Buyer**, **Approver** or **Manager**. See [Company locations](https://docs.sparklayer.io/help/customers/company-locations.md).

### Company user

A colleague a B2B customer invites to share their account, so the team sees the same orders, shopping lists and addresses. Sometimes called a sub-account. See [Company users](https://docs.sparklayer.io/help/customers/company-users.md).

### Main user

The company user who sends the invitations, controls who can access the company account and approves orders from limited users. See [Company users](https://docs.sparklayer.io/help/customers/company-users.md#how-it-works).

### Limited user

A company user who can build orders but not complete them. Their orders go to the main user for approval. See [Limited access](https://docs.sparklayer.io/help/customers/company-users.md#limited-access).

### Sub-account

Another name for a [company user](#company-user). In the [Ignite](https://docs.sparklayer.io/ignite.md) docs, it also means the customer accounts created for company users on the eCommerce platform.

## Sales reps

### Sales agent

A member of your team who signs in to place orders and manage accounts on behalf of B2B customers, also called a sales rep. Their role controls what they can do. See [Sales rep setup](https://docs.sparklayer.io/help/sales-reps.md).

### Sales agent role

A set of permissions that controls what a sales agent can see and do in SparkLayer. See [Roles](https://docs.sparklayer.io/help/sales-reps/roles.md).

### Catalog

The image-first product browser in the storefront widget, for searching, filtering and adding products in a few taps. Sales reps see it as the **Catalog** tab, and customers as **Quick Order**. See [Catalog and Quick Order](https://docs.sparklayer.io/help/sales-ordering/catalog.md).

### Counter mode

A full-screen till for serving customers in person, such as at a trade counter, showroom or trade show. You pick the account, scan or tap products and check out as them. See [Counter mode](https://docs.sparklayer.io/help/sales-ordering/counter-mode.md).

### Pulse

SparkLayer's workspace for sales reps, in early access and on every paid plan with a sales agent seat. A rep opens it from the **Dashboard** tab in the SparkLayer widget on your store. It shows a rep's accounts, orders, carts, quotes, receivables, tasks and who needs attention today. See [Pulse](https://docs.sparklayer.io/help/pulse.md).

### Account health

A score from 0 to 100 that Pulse gives each account, based on how recently it ordered against its usual gap between orders, how its spending is trending and how many orders it has placed. Accounts are banded **Healthy** (75 and above), **Stable** (50 to 74), **At risk** (30 to 49) or **Critical** (below 30). See [How account health is scored](https://docs.sparklayer.io/help/pulse/customers.md#how-account-health-is-scored).

### Usual basket

What an account typically orders: the products on at least half of its orders, each at its usual quantity and the account's own price. Pulse uses it to predict what a reorder will be worth, and puts it in the cart when you click **Order**. See [Reorder radar](https://docs.sparklayer.io/help/pulse/reorder-radar.md).

### Reorder radar

The Pulse screen that tracks how often each account orders, and flags who is due, overdue or has gone quiet. See [Reorder radar](https://docs.sparklayer.io/help/pulse/reorder-radar.md).

### Stale quote

In Pulse, a quote that's still open (**Open** or **Awaiting customer**) and has been open 14 days or more. Pulse shows it as **open 14+ days**. See [Quotes](https://docs.sparklayer.io/help/pulse/quotes.md#how-the-figures-are-worked-out).

## Pricing

### Price list

A set of B2B prices for your products, keyed by SKU. You assign price lists to customer groups or individual customers. See [Price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md).

### Automatic price list

A price list calculated from your store's own prices, for example 50% off retail. See [Price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md).

### Manual price list

A price list where you set exact prices, usually by uploading a CSV file. See [Price lists](https://docs.sparklayer.io/help/pricing/managing-pricing.md).

### Price editor

A tool in the SparkLayer Dashboard for one-off price changes to individual products. See [Price editor](https://docs.sparklayer.io/help/pricing/price-editor.md).

### Quantity pricing

Lower unit prices when a customer buys more, for example 1 at $10 or 10 at $8. Also called tiered pricing or price breaks. See [Quantity pricing](https://docs.sparklayer.io/help/pricing/quantity-pricing.md).

### Unit of measure pricing

Prices set for different units, such as boxes, cartons or pallets. See [Unit of measure pricing](https://docs.sparklayer.io/help/storefront/quantity-rules.md#unit-of-measure-pricing).

### Pack size

The multiple a product must be ordered in, for example units of 6. See [Pack sizing](https://docs.sparklayer.io/help/storefront/quantity-rules.md#product-pack-sizing).

### RRP

Recommended retail price, also known as MSRP. You can show it alongside a customer's B2B price. See [How prices are shown](https://docs.sparklayer.io/help/pricing/pricing-display.md).

### B2B discounts

SparkLayer's own discounts and promotions, such as money off an order, volume tiers and coupon codes, which work on top of price lists. They need the Growth plan. You may also see them called the Discount Engine. See [Discounts](https://docs.sparklayer.io/help/pricing/discounts.md).

## Ordering and payment

### Draft order

An order saved for review rather than completed straight away. On Shopify, orders paid with offline methods, such as Pay on Account and Pay by Invoice, arrive as draft orders by default. See [Shopify payment methods](https://docs.sparklayer.io/help/platforms/shopify/customisations/payment-methods.md).

### Upfront payment

Paying online by card, through your eCommerce platform's checkout, when the order is placed. See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md).

### Pay by Invoice

An offline payment method where the customer places the order and pays later against an invoice, often on net terms. See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md).

### Pay on Account

An offline payment method that charges the order to the customer's account balance, within their credit limit. See [Credit, net terms & invoicing](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md).

### Net terms

The number of days a customer has to pay for an order they didn't pay for at checkout, because they used Pay on Account or Pay by Invoice. For example, Net 30 gives them 30 days. Net terms are on every plan. See [Let trusted customers pay later on Net 30](https://docs.sparklayer.io/help/guides/net-terms.md).

### Credit limit

The maximum balance a customer can have outstanding on their account. It applies to Pay on Account orders, and is on every plan. See [Credit, net terms & invoicing](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md).

### Awaiting merchant

An order the customer has placed in SparkLayer that isn't a completed order in your store yet. Usually it's a Pay on Account or Pay by Invoice order that's still a draft order, waiting for you to complete it (or for **Auto-complete draft orders** to do it); it can also be an order whose sync to your platform hasn't finished. It has a purchase ID, such as P#1264, and shows as **Awaiting merchant** in **Orders** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/activity)), or **SparkLayer Wholesale > Orders** in the Shopify app and in the customer's [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md#order-statuses). Once the order is completed in your store, it becomes a normal order. See [Orders](https://docs.sparklayer.io/help/dashboard/orders.md).

### Quote

A customer's request (or a sales agent's offer) for a price on a set of products, which can be negotiated and then converted into an order. See [Set up quotes](https://docs.sparklayer.io/help/ordering/quoting.md).

### Shopping list

A named list of products a customer saves so they can reorder quickly. See [Shopping lists](https://docs.sparklayer.io/help/ordering/shopping-lists.md).

### Intelligent Cart

AI features in the cart, on the Starter plan and above: **Upload a file** builds a cart from a PDF, photo or forwarded email, and camera barcode scanning adds products by their barcode. Importing a CSV or spreadsheet of SKUs works on every plan. See [Intelligent Cart (AI)](https://docs.sparklayer.io/help/ordering/intelligent-cart.md).

### Timeline

The record of messages, internal notes and events on an order or quote. See [Timeline & communications](https://docs.sparklayer.io/help/customers/timeline.md).

## Setup and storefront

### SparkLayer Dashboard

The admin area at [app.sparklayer.io](https://app.sparklayer.io), with a grouped sidebar, where you manage pricing, companies, customers, settings and integrations. On Shopify, the same screens are also in the [SparkLayer Wholesale](#sparklayer-wholesale) app, and on Wix in the SparkLayer app in your Wix dashboard. See [Find your way around SparkLayer](https://docs.sparklayer.io/help/dashboard.md).

### SparkLayer Wholesale

SparkLayer's app inside Shopify admin, under **Sales channels**. It has the same screens as the SparkLayer Dashboard, except Forms and Data tables, with one menu item per area and its pages as tabs. See [Three versions of the same app](https://docs.sparklayer.io/help/dashboard.md#two-versions).

### Explore features

A screen that lists what SparkLayer can do, with the plan each feature needs and a way to set it up or preview it. See [Explore features](https://docs.sparklayer.io/help/dashboard/plan-and-features.md#explore-features).

### Theme setup

The Shopify screen that shows which SparkLayer blocks are on your theme, and opens the theme editor at any of them. See [Theme setup](https://docs.sparklayer.io/help/platforms/shopify/theme-setup.md).

### Platform connection

The link between SparkLayer and your eCommerce platform (Shopify, BigCommerce, Wix, WooCommerce or Magento). See [Managing integrations](https://docs.sparklayer.io/help/integrations/managing-integrations.md), or [Platform connection](https://docs.sparklayer.io/ignite/platform-connection.md) if you're building an Ignite integration.

### API key

A pair of credentials (a client ID and a secret) that lets another system, such as your ERP, read and write your SparkLayer data. You create it at **Settings > API** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/api)), or **SparkLayer Wholesale > Settings > API** in the Shopify app (Pro plan) for your developer or integration partner, and treat it like a password. See [API](https://docs.sparklayer.io/help/dashboard/settings.md#api).

### iPaaS

Integration platform as a service: a tool such as Patchworks or Zynk that connects systems which don't talk to each other directly, such as an ERP and SparkLayer. See [Integrations](https://docs.sparklayer.io/help/integrations.md).

### Source of truth

The one system whose data wins when 2 systems disagree. If your ERP is the source of truth for prices, you change prices there and the change flows into SparkLayer, not the other way round. See [Integrations](https://docs.sparklayer.io/help/integrations.md).

### Site ID

The unique identifier for your SparkLayer site, used when setting up frontend interfaces, forms and the API. See [Your account and team](https://docs.sparklayer.io/help/dashboard/account.md#edit-your-account-details).

### Site environment

A store connected to your SparkLayer account. With test mode, one account has a live (production) environment and a test (staging) environment. See [Test mode](https://docs.sparklayer.io/help/dashboard/test-mode.md).

### Test mode

A way to switch the SparkLayer Dashboard between your live store and a test store, so you can try changes without affecting live customers. See [Test mode](https://docs.sparklayer.io/help/dashboard/test-mode.md).

### Product and customer sync

The process that copies product and customer data from your eCommerce platform into SparkLayer (also known as data sync). Product sync has its own screen, **Pricing > Products** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/products)), or **SparkLayer Wholesale > Integrations > Product sync** in the Shopify app, and customer sync problems show as a banner on **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app. See [Product and customer sync](https://docs.sparklayer.io/help/integrations/data-sync.md).

### Metafields

Extra fields stored against products or customers in your eCommerce platform, which SparkLayer reads for settings such as pack sizes. See [Metafields](https://docs.sparklayer.io/developers/data/metafields.md).

### Core Script

The SparkLayer code in your store's theme that loads SparkLayer on your storefront, added when SparkLayer is installed. You don't normally need to touch it, but your developer or agency may change its settings for advanced changes, such as custom checkout fields or changing text in code. See [Add a Core Script setting](https://docs.sparklayer.io/help/storefront/storefront-options.md#add-a-core-script-setting).

### Frontend interfaces

The B2B components SparkLayer adds to your storefront, such as My Cart, My Account and product pricing. See [Storefront widgets](https://docs.sparklayer.io/help/storefront/interfaces.md).

### Widgets

Another name for SparkLayer's [frontend interfaces](#frontend-interfaces): the B2B pricing, cart and account area your customers see on your store. You add them to your theme from **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app.

### Custom slots

Places in SparkLayer's frontend interfaces where you can add your own HTML content. See [Custom slots (targets)](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md).

### Hybrid store

A single store that serves both retail (DTC) and B2B customers. The alternative is a standalone B2B store. See [Shopify B2B store setup](https://docs.sparklayer.io/help/platforms/shopify/customisations/store-setup.md).

### B2B Catalogs

A free Shopify app that controls which products and variants each customer group can see. See [B2B Catalogs](https://docs.sparklayer.io/help/storefront/b2b-catalogs.md).

### Ignite

SparkLayer's framework for connecting platforms that don't have a ready-made integration. See [SparkLayer Ignite](https://docs.sparklayer.io/ignite.md).


---

# Policies

URL: https://docs.sparklayer.io/help/policies

Find SparkLayer's privacy, security, business continuity, incident management, terms of service and refund policies, most of them in the Trust Center.

> **Quick summary**
>
> - SparkLayer's privacy, security, business continuity, incident management and terms of service documents are published in the [SparkLayer Trust Center](https://www.sparklayer.io/trust/).
> - The [refund policy](https://docs.sparklayer.io/help/policies/refund-policy.md) is here in the Help Center.
> - Questions about any policy: email [contact@sparklayer.io](mailto:contact@sparklayer.io).

SparkLayer's security, privacy and legal documents are published in the [SparkLayer Trust Center](https://www.sparklayer.io/trust/). The Trust Center always has the current version of each document, so it's the place to send anyone doing a security or procurement review. If you have questions about any of them, email [contact@sparklayer.io](mailto:contact@sparklayer.io).

## Trust Center documents

| Policy | What it covers |
| --- | --- |
| [Privacy policy](https://www.sparklayer.io/privacy) | The personal data SparkLayer handles as a controller and as a processor, our sub-processors and the rights available to you. |
| [Security policy](https://www.sparklayer.io/trust/security) | Hosting, encryption, authentication, access control, secure development, backups and review. |
| [Business continuity plan](https://www.sparklayer.io/trust/business-continuity) | How we prepare for disruption, restore service and keep customers informed. |
| [Incident management policy](https://www.sparklayer.io/trust/incident-management) | How incidents are classified, contained and resolved, and how to report a security concern. |
| [Terms of service](https://www.sparklayer.io/terms-of-service/) | The terms that apply to your use of SparkLayer. |

## Billing

| Policy | What it covers |
| --- | --- |
| [Refund policy](https://docs.sparklayer.io/help/policies/refund-policy.md) | When refunds are available for monthly and annual plans, what isn't refundable, how to request a refund and how Shopify billing works. |

## Next steps

- [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md): How plans are billed on each platform and how to cancel
- [Contact support](https://docs.sparklayer.io/help/support.md): How to reach our team and how quickly we reply


---

# Refund policy

URL: https://docs.sparklayer.io/help/policies/refund-policy

SparkLayer's refund policy: when monthly and annual plans can be refunded, trial overruns, what isn't refundable, how to ask for a refund and Shopify billing.

> **Quick summary**
>
> - Refunds are for significant technical problems that cause data loss or major disruption, and only when we can't provide a fix.
> - Request a refund within **5 days** of the current billing period on a monthly plan, or **7 days** on an annual plan, by emailing [support@sparklayer.io](mailto:support@sparklayer.io).
> - Keep the app installed until we've looked into the problem: once it's uninstalled, your data is removed and we can't help.
> - On Shopify, billing and refunds go through Shopify's system, not SparkLayer.

This policy applies to all SparkLayer services, on every supported eCommerce platform and app. If you have a billing question, a technical issue or need development help, contact us at [support@sparklayer.io](mailto:support@sparklayer.io) before you request a refund.

We aim to respond within **24 hours on weekdays** and **48–72 hours over weekends** (see [Response times](https://docs.sparklayer.io/help/support.md#response-times)). We consider a refund request in full once we've reviewed the issue and tried to resolve it.

## Eligibility

Refunds are only issued for significant technical problems that cause data loss or major disruption, and only when a fix can't be provided.

| Situation | When to request | What you can get |
| --- | --- | --- |
| **Monthly subscription** | Within **5 days** of the current billing period. | A refund, if approved. |
| **Annual subscription** | Within **7 days** of the current billing period. | A refund, if approved. If you cancel an annual plan mid-term, an approved refund is the total paid, minus the months used (at the original monthly rate) and any Shopify processing fees. |
| **Trial overrun** (you forgot to cancel before a trial ended) | Within 5 days (monthly) or 7 days (annual). | **50% off** the first billing cycle. |

## What isn't refundable

As we offer a free trial for evaluation, we don't offer refunds for:

- A change of mind or an accidental purchase
- Apps bought at a reduced price or used only for testing
- Not having the technical ability to use the app
- Requests for goodwill, previous billing periods or custom development services
- Conflicts caused by third-party themes or other apps

## How to request a refund

1. **Contact support:** email us at [support@sparklayer.io](mailto:support@sparklayer.io).
2. **Provide evidence:** include screenshots, videos or URLs to help us diagnose the issue.
3. **Keep the app installed:** don't uninstall the app before you contact us. We can only investigate issues while the app is installed. Once it's uninstalled, your data is removed and we can't help.

## Processing and Shopify billing

| Topic | How it works |
| --- | --- |
| **Approval** | If your refund is approved and you've already been charged, it's processed immediately. If the charge is still pending, you may need to wait for the eCommerce provider to complete the billing cycle. |
| **Shopify users** | App billing and refunds are managed by Shopify's system, not SparkLayer, so we can't stop future Shopify charges directly. Refunds through Shopify can only be issued after the current billing cycle is complete. You can also contact Shopify directly about charges. |

## Before you uninstall

If you plan to remove SparkLayer, contact us first. We can help remove any remaining app code and make sure uninstalling doesn't affect your store's performance. For how cancelling works on your platform, and what uninstalling deletes, see [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md).

## Next steps

- [Billing, trials and cancelling](https://docs.sparklayer.io/help/dashboard/billing.md): How plans are billed on each platform and how to cancel
- [Contact support](https://docs.sparklayer.io/help/support.md): Contact our team about a problem before asking for a refund
- [Policies](https://docs.sparklayer.io/help/policies.md): SparkLayer's privacy, security and terms of service documents


---

# Developer documentation

URL: https://docs.sparklayer.io/developers

Build on SparkLayer with the REST APIs, JavaScript SDK, storefront templates and Ignite, and make your first authenticated API call in a few minutes.

SparkLayer adds B2B ordering to the eCommerce platform you already use, such as Shopify. These pages are for developers who connect SparkLayer to other systems, or change how it works on a store.

New to SparkLayer? Start with [How SparkLayer connects](https://docs.sparklayer.io/developers/architecture.md). It explains which system holds which data, and that decides what you need to build.

## Choose what to build

- [REST APIs](https://docs.sparklayer.io/developers/api.md): Send price lists, stock levels and orders between your business systems, such as an ERP, and SparkLayer.
- [Frontend integration](https://docs.sparklayer.io/developers/frontend.md): Add SparkLayer to your store's theme, hide retail-only parts of the page from B2B customers, and match it to your design.
- [JavaScript SDK](https://docs.sparklayer.io/developers/javascript-sdk.md): Write your own code to change how SparkLayer behaves on your store, or build a headless storefront.
- [Templates](https://docs.sparklayer.io/developers/templates.md): Change the invoice and quote PDFs, and the emails SparkLayer sends, with Liquid templates.
- [Ignite](https://docs.sparklayer.io/ignite.md): Use SparkLayer on an eCommerce platform it doesn't have a ready-made integration for.
- [Data and limits](https://docs.sparklayer.io/developers/data.md): Look up metafield keys for product, customer and order data, and the limits to design around.

Not sure which you need? [Building integrations](https://docs.sparklayer.io/developers/building-integrations.md) compares building on the API yourself with using a middleware partner, or [ask our support team](https://docs.sparklayer.io/help/support.md).

## Make your first API call

**Step 1.** **Check your plan**

API access is on the [Pro and Enterprise plans](https://www.sparklayer.io/pricing/).

**Step 2.** **Follow the quickstart**

The [quickstart](https://docs.sparklayer.io/developers/quickstart.md) takes you from no credentials to a working API call: create an API key, get an access token and call an endpoint.

**Step 3.** **Learn the rules every call follows**

How to [authenticate](https://docs.sparklayer.io/developers/authentication.md), what the APIs return when something goes wrong ([errors](https://docs.sparklayer.io/developers/errors.md)), and how long lists come back in pages ([pagination](https://docs.sparklayer.io/developers/pagination.md)).

**Step 4.** **Pick the APIs you need**

The [API overview](https://docs.sparklayer.io/developers/api.md) says what each API does and which ones most integrations use.

## Build with AI

These docs are written to work with AI assistants. Pick a ready-made prompt below, add a line about your setup, and open it in Claude or ChatGPT. Each prompt tells the assistant which pages to read and what a finished, production-ready result looks like. [Build with AI](https://docs.sparklayer.io/developers/build-with-ai.md) has every prompt, plus the docs MCP server and the OpenAPI specs.

### Sync prices from your ERP

Push price lists and SKU prices from your ERP or PIM into SparkLayer on a schedule.

```text
I want you to build a scheduled job that keeps my B2B price lists and prices in SparkLayer in step with my ERP, using SparkLayer, the B2B ordering platform.
My setup: [describe your system, language and hosting]

Before writing any code, read these SparkLayer docs (Markdown versions):
- https://docs.sparklayer.io/developers/authentication.md: getting and using an access token
- https://docs.sparklayer.io/developers/api/pricing.md: how price lists and prices fit together
- https://docs.sparklayer.io/developers/api/pricing/get-price-lists-v2.md: listing existing price lists (paginated)
- https://docs.sparklayer.io/developers/api/pricing/create-a-price-list.md: creating missing price lists
- https://docs.sparklayer.io/developers/api/pricing/update-pricing-by-price-list.md: updating the prices in one price list
- https://docs.sparklayer.io/developers/api/pricing/update-pricing-for-multiple-price-lists.md: updating prices across price lists in one call
- https://docs.sparklayer.io/developers/api/sync-log.md: recording each sync so it shows in the SparkLayer Dashboard
- https://docs.sparklayer.io/developers/errors.md: error format and retries
- https://docs.sparklayer.io/developers/pagination.md: paging through price lists
If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation.

Facts that apply to every SparkLayer API call:
- Base URLs: Live `https://app.sparklayer.io`, test `https://test.app.sparklayer.io`. Each environment has its own data and its own API keys.
- Access: API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
- Access token: `POST {base}/api/auth/token` with a `Site-Id` header and a JSON body (not form-encoded): `{"grant_type":"client_credentials","client_id":"…","client_secret":"…"}`. It returns `access_token`, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires.
- Every request: `Authorization: Bearer <access_token>` and `Site-Id: <site id>`, plus `Content-Type: application/json` when there is a body. Set a `User-Agent` that names your integration.
- Errors: RFC 7807 problem details: `title`, `status`, `detail` and an optional `errors[]` of `{ code, message, property }`. Some error responses have no body. Retry `5xx`, `429` (honouring `Retry-After`) and concurrent-update `409`s with exponential backoff; on `401`, get a new token once and retry; don't retry other `4xx` without changing the request.
- Pagination: Most list endpoints return everything. `GET /api/v2/price-lists` pages with `page` and `page_size` (up to 250) until `pagination.current_page` equals `total_pages`. `GET /api/v1/purchases` uses `limit` (up to 500) and `offset`: stop when a page has fewer than `limit` results.
- Ground rules: Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer `GET /api/v2/price-lists` over the deprecated v1. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code.

Steps:
1. Read the price lists and prices (including any quantity price breaks) from my ERP.
2. Fetch every SparkLayer price list with `GET /api/v2/price-lists`, following the pagination.
3. Create any price list that exists in my ERP but not in SparkLayer with `POST /api/v1/price-lists`, as the Pricing API docs describe for price lists managed by an external system.
4. Send the prices for each price list with `PATCH /api/v1/price-lists/{slug}/pricing`, or several price lists at once with `PATCH /api/v1/batch-update-pricing`, matching products by SKU and keeping each request within the documented limits.
5. Record each run with the Sync Logging API: a full sync for a complete run, a partial sync for changes only.

Requirements:
- Keep credentials (Site ID, Client ID, Client Secret) in environment variables or a secrets manager, never in code.
- Cache the access token and request a new one shortly before it expires.
- Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409 responses with exponential backoff; on a 401, get a new token once and retry. Log every failed request with its status, `title` and `detail`.
- Make each run safe to repeat, so a failed run can simply be run again.
- Add a dry-run mode that logs what would change without calling the write endpoints.
- Only send prices that changed since the last successful run, if my ERP can tell me.
- Report SKUs that SparkLayer rejects, with the reason from the error response.
- Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing.

Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first.
```

### Keep stock levels in sync

Send stock levels per SKU and location from your ERP or WMS every few minutes.

```text
I want you to build a scheduled job that keeps SparkLayer stock levels in step with my stock system, using SparkLayer, the B2B ordering platform.
My setup: [describe your system, language and hosting]

Before writing any code, read these SparkLayer docs (Markdown versions):
- https://docs.sparklayer.io/developers/authentication.md: getting and using an access token
- https://docs.sparklayer.io/developers/api/stock.md: stock levels and stock locations
- https://docs.sparklayer.io/developers/api/stock/list-stock-locations.md: the stock locations SparkLayer knows about
- https://docs.sparklayer.io/developers/api/stock/update-stock-levels.md: updating stock for many SKUs in one call
- https://docs.sparklayer.io/developers/api/sync-log.md: recording each sync
- https://docs.sparklayer.io/developers/errors.md: error format and retries
If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation.

Facts that apply to every SparkLayer API call:
- Base URLs: Live `https://app.sparklayer.io`, test `https://test.app.sparklayer.io`. Each environment has its own data and its own API keys.
- Access: API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
- Access token: `POST {base}/api/auth/token` with a `Site-Id` header and a JSON body (not form-encoded): `{"grant_type":"client_credentials","client_id":"…","client_secret":"…"}`. It returns `access_token`, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires.
- Every request: `Authorization: Bearer <access_token>` and `Site-Id: <site id>`, plus `Content-Type: application/json` when there is a body. Set a `User-Agent` that names your integration.
- Errors: RFC 7807 problem details: `title`, `status`, `detail` and an optional `errors[]` of `{ code, message, property }`. Some error responses have no body. Retry `5xx`, `429` (honouring `Retry-After`) and concurrent-update `409`s with exponential backoff; on `401`, get a new token once and retry; don't retry other `4xx` without changing the request.
- Pagination: Most list endpoints return everything. `GET /api/v2/price-lists` pages with `page` and `page_size` (up to 250) until `pagination.current_page` equals `total_pages`. `GET /api/v1/purchases` uses `limit` (up to 500) and `offset`: stop when a page has fewer than `limit` results.
- Ground rules: Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer `GET /api/v2/price-lists` over the deprecated v1. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code.

Steps:
1. Read current stock levels per SKU (and per warehouse, if I have several) from my stock system.
2. Map my warehouses to SparkLayer stock locations from `GET /api/v1/stock-locations`, and tell me if any are missing rather than guessing.
3. Send the levels with `POST /api/v1/batch-update-stock`, matching products by SKU, in batches within the documented limits.
4. Record each run with the Sync Logging API.

Requirements:
- Keep credentials (Site ID, Client ID, Client Secret) in environment variables or a secrets manager, never in code.
- Cache the access token and request a new one shortly before it expires.
- Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409 responses with exponential backoff; on a 401, get a new token once and retry. Log every failed request with its status, `title` and `detail`.
- Make each run safe to repeat, so a failed run can simply be run again.
- Add a dry-run mode that logs what would change without calling the write endpoints.
- Send only SKUs whose stock changed since the last run, if my system can tell me.
- Never send a negative stock level unless the docs say it is allowed.
- Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing.

Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first.
```

### Send B2B orders to your ERP

Pick up new and updated B2B orders from SparkLayer and create them in your ERP.

```text
I want you to build a job that picks up new and updated B2B orders from SparkLayer and creates or updates them in my ERP, using SparkLayer, the B2B ordering platform.
My setup: [describe your system, language and hosting]

Before writing any code, read these SparkLayer docs (Markdown versions):
- https://docs.sparklayer.io/developers/authentication.md: getting and using an access token
- https://docs.sparklayer.io/developers/api/purchasing.md: what a purchase is and how orders, quotes and carts differ
- https://docs.sparklayer.io/developers/api/purchasing/get-purchases.md: listing orders with filters
- https://docs.sparklayer.io/developers/api/purchasing/get-purchase.md: fetching one order in full
- https://docs.sparklayer.io/developers/pagination.md: offset paging through purchases
- https://docs.sparklayer.io/developers/errors.md: error format and retries
If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation.

Facts that apply to every SparkLayer API call:
- Base URLs: Live `https://app.sparklayer.io`, test `https://test.app.sparklayer.io`. Each environment has its own data and its own API keys.
- Access: API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
- Access token: `POST {base}/api/auth/token` with a `Site-Id` header and a JSON body (not form-encoded): `{"grant_type":"client_credentials","client_id":"…","client_secret":"…"}`. It returns `access_token`, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires.
- Every request: `Authorization: Bearer <access_token>` and `Site-Id: <site id>`, plus `Content-Type: application/json` when there is a body. Set a `User-Agent` that names your integration.
- Errors: RFC 7807 problem details: `title`, `status`, `detail` and an optional `errors[]` of `{ code, message, property }`. Some error responses have no body. Retry `5xx`, `429` (honouring `Retry-After`) and concurrent-update `409`s with exponential backoff; on `401`, get a new token once and retry; don't retry other `4xx` without changing the request.
- Pagination: Most list endpoints return everything. `GET /api/v2/price-lists` pages with `page` and `page_size` (up to 250) until `pagination.current_page` equals `total_pages`. `GET /api/v1/purchases` uses `limit` (up to 500) and `offset`: stop when a page has fewer than `limit` results.
- Ground rules: Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer `GET /api/v2/price-lists` over the deprecated v1. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code.

Steps:
1. List orders with `GET /api/v1/purchases`, filtered to orders updated since the last successful run (use the documented date filters, not my own), paging with `limit` and `offset`.
2. Fetch each order in full if the list response lacks fields I need, and map it to my ERP's sales order format, including lines, prices, tax, shipping and the customer.
3. Create the order in my ERP, or update it if it was already sent, keyed on the SparkLayer order ID so nothing is created twice.
4. Store the timestamp of the last order processed and resume from it on the next run.

Requirements:
- Keep credentials (Site ID, Client ID, Client Secret) in environment variables or a secrets manager, never in code.
- Cache the access token and request a new one shortly before it expires.
- Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409 responses with exponential backoff; on a 401, get a new token once and retry. Log every failed request with its status, `title` and `detail`.
- Make each run safe to repeat, so a failed run can simply be run again.
- Add a dry-run mode that logs what would change without calling the write endpoints.
- Don't write anything back to SparkLayer unless the docs show an endpoint for it.
- Show me the field mapping as a table before writing the code.
- Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing.

Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first.
```


---

# How SparkLayer connects

URL: https://docs.sparklayer.io/developers/architecture

How SparkLayer sits alongside your eCommerce platform and backend systems: B2B data syncs through the SparkLayer API while the Frontend adds wholesale features.

SparkLayer works alongside your eCommerce platform; it doesn't replace it. Your platform still runs your catalogue, your customers, checkout and orders. SparkLayer adds what B2B buyers need on top, such as their own prices, pack sizes and ordering rules.

How SparkLayer connects:

- **Backend:** B2B-specific data (price lists, product pack sizes, customer rules) comes from an ERP / CRM, a manual upload or an automatic sync, and is sent to the **SparkLayer Backend**, which stores it.
- **eCommerce platform** (e.g. Shopify): its core functions (order, catalogue and customer management, analytics, marketing and promotions, CMS) sync both ways with the **SparkLayer Connector**.
- **Website storefront:** core templates (homepage, collections, products, static pages, blog) work as normal. The **SparkLayer Frontend** overlays B2B widgets: product pricing, buy button, quick order form, checkout and ordering, and the My Account area.

## The three parts of SparkLayer

| Part | What it does |
| --- | --- |
| **Backend** | Stores your B2B data, such as price lists, pack sizes and customer rules. Your backend systems send it through the [SparkLayer API](https://docs.sparklayer.io/developers/api.md), or you add it with the import tools in the [Dashboard](https://docs.sparklayer.io/help/dashboard.md). |
| **Connector** | Keeps SparkLayer and your eCommerce platform in step, in both directions. Products and customers come in from your platform: see [Product and customer sync](https://docs.sparklayer.io/help/integrations/data-sync.md). |
| **Frontend** | Adds B2B features to your storefront, such as customer-specific prices, quick order and the My Account area. The rest of your site works as normal. See [Frontend integration](https://docs.sparklayer.io/developers/frontend.md). |

## What this means for your integration

- **Keep products and customers on your eCommerce platform.** SparkLayer reads them from there, so you don't send them to SparkLayer.
- **Send B2B data from the system that owns it.** Prices and stock usually live in your ERP, which is their [source of truth](https://docs.sparklayer.io/help/glossary.md#source-of-truth): send them to SparkLayer with the API, and change them in the ERP, not in SparkLayer.
- **No ready-made integration for your platform?** With [Ignite](https://docs.sparklayer.io/ignite.md), you build the Connector yourself.

## Next steps

- [SparkLayer API](https://docs.sparklayer.io/developers/api.md): What each API does, and which ones your integration needs.
- [Building integrations](https://docs.sparklayer.io/developers/building-integrations.md): Build the integration yourself, or use a middleware partner.
- [Data limitations](https://docs.sparklayer.io/developers/data/data-limitations.md): Recommended and hard limits on the data you send.
- [SparkLayer Ignite](https://docs.sparklayer.io/ignite.md): Connect SparkLayer to a platform without a ready-made integration.


---

# Building integrations

URL: https://docs.sparklayer.io/developers/building-integrations

Choose how to connect your ERP or CRM to SparkLayer: build a direct integration with the SparkLayer API or use a middleware partner such as an iPaaS.

If your B2B data lives in a backend system, such as an ERP or CRM, you can send it to SparkLayer automatically instead of keeping it up to date by hand. There are two ways to connect them.

## Choose how to connect

| Option | How it works | Who builds it | Choose it when |
| --- | --- | --- | --- |
| **Direct connection** | You build an integration between your backend system and SparkLayer with the [SparkLayer API](https://docs.sparklayer.io/developers/api.md). | Your developers, or an agency | You have developers, or you need full control over what syncs and when. |
| **Middleware connection** | A middleware tool you already use, such as an [iPaaS](https://docs.sparklayer.io/help/glossary.md#ipaas), passes the data between your backend system and SparkLayer. | Your middleware partner's team | Your systems already connect through middleware, and it supports SparkLayer. |

Either way, your backend system keeps talking to your eCommerce platform as it does today. Only the B2B data, such as price lists, pack sizes and payment terms, goes to SparkLayer.

How data flows between systems:

1. Your backend system (e.g. Brightpearl, Oracle NetSuite, Microsoft Dynamics, Cegid, SEKO, SAP, OrderWise) holds the B2B data that's typically synchronised: B2B pricing (e.g. price lists), product rules (e.g. pack sizing) and customer rules (e.g. payment terms).
2. It's integrated with both Shopify and SparkLayer, via a direct connection or a middleware connection.
3. Specific B2B data syncs to SparkLayer; product, customer and order data syncs to Shopify.
4. SparkLayer connects to Shopify and enables the B2B portal with your synchronised B2B data.

## Check for a ready-made integration

SparkLayer already integrates with many backend systems, so you may not need to build anything. See the [full list of integrations](https://www.sparklayer.io/integrations/index.html).

To talk through how SparkLayer works with your systems, contact our [support team](https://docs.sparklayer.io/help/support.md).

## Next steps

- [API quickstart](https://docs.sparklayer.io/developers/quickstart.md): make your first SparkLayer API request.
- [SparkLayer API](https://docs.sparklayer.io/developers/api.md): which APIs your integration needs.
- [SparkLayer Ignite](https://docs.sparklayer.io/ignite.md): connect SparkLayer to a platform without a ready-made integration.


---

# Quickstart

URL: https://docs.sparklayer.io/developers/quickstart

Make your first SparkLayer API call in about five minutes: create an API key in the Dashboard, request an access token and list your price lists.

This guide takes you from no credentials to a successful API call. You need a SparkLayer account on the [Pro or Enterprise plan](https://www.sparklayer.io/pricing/) and a terminal with `curl` (and [`jq`](https://jqlang.org), to read the token from the response).

> **Use the test environment first**
>
> If your account has [Test mode](https://docs.sparklayer.io/help/dashboard/test-mode.md) set up, create your first key in the test environment and call `https://test.app.sparklayer.io`. Test and live hold separate data, so you can experiment without affecting your live store.

**Step 1.** **Create an API key**

In the SparkLayer Dashboard, go to **Settings > API** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/api)), or **SparkLayer Wholesale > Settings > API** in the Shopify app. For a test key, turn on **Test mode** in the left-hand menu first.

Select **Create new API Key**, enter a name such as `Quickstart`, and copy the three values shown:

| Value | Used as |
| --- | --- |
| Site ID | The `Site-Id` header on every request |
| Client ID | `client_id` when you request a token |
| Client Secret | `client_secret` when you request a token: shown once |

**Step 2.** **Save your credentials in your shell**

So the commands below run as they are, put your values in environment variables. For the test environment, set `SPARKLAYER_BASE_URL` to `https://test.app.sparklayer.io`.

```bash title="Terminal"
export SPARKLAYER_BASE_URL="https://app.sparklayer.io"
export SPARKLAYER_SITE_ID="<SITE_ID>"
export SPARKLAYER_CLIENT_ID="<CLIENT_ID>"
export SPARKLAYER_CLIENT_SECRET="<CLIENT_SECRET>"
```

**Step 3.** **Request an access token**

Exchange the client ID and secret for an access token. The request body is JSON, and the `Site-Id` header is required here too:

```bash title="Terminal"
curl -s -X POST "$SPARKLAYER_BASE_URL/api/auth/token" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"grant_type\": \"client_credentials\",
    \"client_id\": \"$SPARKLAYER_CLIENT_ID\",
    \"client_secret\": \"$SPARKLAYER_CLIENT_SECRET\"
  }"
```

The response contains your token, which is valid for one hour (`expires_in` is in seconds):

```json title="Response"
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "<ACCESS_TOKEN>"
}
```

To keep the token in a variable for the next step, run the same request through `jq`:

```bash title="Terminal"
export SPARKLAYER_TOKEN=$(curl -s -X POST "$SPARKLAYER_BASE_URL/api/auth/token" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"$SPARKLAYER_CLIENT_ID\",\"client_secret\":\"$SPARKLAYER_CLIENT_SECRET\"}" \
  | jq -r .access_token)
```

**Step 4.** **Call an endpoint**

List your price lists with the [Pricing API](https://docs.sparklayer.io/developers/api/pricing/get-price-lists-v2.md), sending the token in the `Authorization` header and your Site ID in the `Site-Id` header:

```bash title="Terminal"
curl -s "$SPARKLAYER_BASE_URL/api/v2/price-lists?page=1&page_size=100" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "User-Agent: quickstart/1.0"
```

You get back a page of price lists, with an empty `data` list if your site has none yet:

```json title="Response"
{
  "data": [
    {
      "slug": "base-list",
      "name": "Base Price List",
      "currency_code": "GBP",
      "source": "custom",
      "tax_inclusive_display": false
    }
  ],
  "pagination": {
    "total": 1,
    "per_page": 100,
    "current_page": 1,
    "total_pages": 1
  }
}
```

## The same in code

The same two calls as a script you can build on. It reads the same environment variables.

**Node.js:**

Node.js 18 or later, with no dependencies:

```javascript title="quickstart.mjs"
const { SPARKLAYER_BASE_URL, SPARKLAYER_SITE_ID, SPARKLAYER_CLIENT_ID, SPARKLAYER_CLIENT_SECRET } =
  process.env;

const tokenResponse = await fetch(`${SPARKLAYER_BASE_URL}/api/auth/token`, {
  method: 'POST',
  headers: { 'Site-Id': SPARKLAYER_SITE_ID, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'client_credentials',
    client_id: SPARKLAYER_CLIENT_ID,
    client_secret: SPARKLAYER_CLIENT_SECRET,
  }),
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

const response = await fetch(`${SPARKLAYER_BASE_URL}/api/v2/price-lists?page=1&page_size=100`, {
  headers: {
    'Site-Id': SPARKLAYER_SITE_ID,
    Authorization: `Bearer ${access_token}`,
    'User-Agent': 'quickstart/1.0',
  },
});
if (!response.ok) throw new Error(`Request failed: ${response.status} ${await response.text()}`);
const { data, pagination } = await response.json();
console.log(`${pagination.total} price lists:`, data.map((list) => list.slug));
```

```bash title="Terminal"
node quickstart.mjs
```

**Python:**

Python 3.9 or later, with [`requests`](https://pypi.org/project/requests/):

```python title="quickstart.py"
import os

import requests

base_url = os.environ["SPARKLAYER_BASE_URL"]
site_id = os.environ["SPARKLAYER_SITE_ID"]

token_response = requests.post(
    f"{base_url}/api/auth/token",
    headers={"Site-Id": site_id},
    json={
        "grant_type": "client_credentials",
        "client_id": os.environ["SPARKLAYER_CLIENT_ID"],
        "client_secret": os.environ["SPARKLAYER_CLIENT_SECRET"],
    },
    timeout=30,
)
token_response.raise_for_status()
access_token = token_response.json()["access_token"]

response = requests.get(
    f"{base_url}/api/v2/price-lists",
    params={"page": 1, "page_size": 100},
    headers={
        "Site-Id": site_id,
        "Authorization": f"Bearer {access_token}",
        "User-Agent": "quickstart/1.0",
    },
    timeout=30,
)
response.raise_for_status()
body = response.json()
print(f"{body['pagination']['total']} price lists:", [p["slug"] for p in body["data"]])
```

```bash title="Terminal"
python quickstart.py
```

For a production integration, reuse the token until it's close to expiry instead of requesting one per call: see [Reuse the access token](https://docs.sparklayer.io/developers/authentication.md#reuse-the-access-token).

## If something goes wrong

| Response | What to check |
| --- | --- |
| `400` from `/api/auth/token` | The `Site-Id` and `Content-Type: application/json` headers are set, and the body includes all three fields |
| `401` from `/api/auth/token` | The client ID and secret are correct and belong to the environment you're calling: live keys only work with `https://app.sparklayer.io`, test keys with `https://test.app.sparklayer.io` |
| `401` or `403` from an API endpoint | The `Authorization` header is `Bearer ` followed by the token, the token is less than an hour old, and you're sending the same `Site-Id` and base URL you requested the token with |
| `jq: command not found` | Install `jq`, or copy `access_token` from the response by hand: `export SPARKLAYER_TOKEN="<ACCESS_TOKEN>"` |

See [Errors](https://docs.sparklayer.io/developers/errors.md) for the error format and every status code.

## Next steps

- [Build with AI](https://docs.sparklayer.io/developers/build-with-ai.md): Ready-made prompts for syncing prices, stock and orders
- [Authentication](https://docs.sparklayer.io/developers/authentication.md): Environments, token reuse and authentication errors
- [API overview](https://docs.sparklayer.io/developers/api.md): Find the APIs your integration needs

Every endpoint page in the API reference also has a playground: enter your token and Site ID to try requests from your browser.


---

# Build with AI

URL: https://docs.sparklayer.io/developers/build-with-ai

Build SparkLayer integrations with Claude, ChatGPT, Cursor or Claude Code: prompts for common jobs, Markdown docs, OpenAPI specs and the docs MCP server.

These docs are built to work with AI assistants such as Claude, ChatGPT and Cursor. There are three ways in:

- **Start from a ready-made prompt** for a common job, such as syncing prices from your ERP.
- **Point your assistant at the docs.** Every page has a Markdown version, and each API has an OpenAPI spec to download.
- **Connect the docs MCP server**, so your assistant can search and read the docs while it writes code.

## Ready-made prompts

Pick a job, add a line about your setup, and open the prompt in your assistant. Each prompt tells the assistant which pages to read, the facts every SparkLayer API call depends on, and what a production-ready result looks like: credentials in environment variables, retries, logging, a dry run and tests.

### Sync prices from your ERP

Push price lists and SKU prices from your ERP or PIM into SparkLayer on a schedule.

```text
I want you to build a scheduled job that keeps my B2B price lists and prices in SparkLayer in step with my ERP, using SparkLayer, the B2B ordering platform.
My setup: [describe your system, language and hosting]

Before writing any code, read these SparkLayer docs (Markdown versions):
- https://docs.sparklayer.io/developers/authentication.md: getting and using an access token
- https://docs.sparklayer.io/developers/api/pricing.md: how price lists and prices fit together
- https://docs.sparklayer.io/developers/api/pricing/get-price-lists-v2.md: listing existing price lists (paginated)
- https://docs.sparklayer.io/developers/api/pricing/create-a-price-list.md: creating missing price lists
- https://docs.sparklayer.io/developers/api/pricing/update-pricing-by-price-list.md: updating the prices in one price list
- https://docs.sparklayer.io/developers/api/pricing/update-pricing-for-multiple-price-lists.md: updating prices across price lists in one call
- https://docs.sparklayer.io/developers/api/sync-log.md: recording each sync so it shows in the SparkLayer Dashboard
- https://docs.sparklayer.io/developers/errors.md: error format and retries
- https://docs.sparklayer.io/developers/pagination.md: paging through price lists
If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation.

Facts that apply to every SparkLayer API call:
- Base URLs: Live `https://app.sparklayer.io`, test `https://test.app.sparklayer.io`. Each environment has its own data and its own API keys.
- Access: API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
- Access token: `POST {base}/api/auth/token` with a `Site-Id` header and a JSON body (not form-encoded): `{"grant_type":"client_credentials","client_id":"…","client_secret":"…"}`. It returns `access_token`, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires.
- Every request: `Authorization: Bearer <access_token>` and `Site-Id: <site id>`, plus `Content-Type: application/json` when there is a body. Set a `User-Agent` that names your integration.
- Errors: RFC 7807 problem details: `title`, `status`, `detail` and an optional `errors[]` of `{ code, message, property }`. Some error responses have no body. Retry `5xx`, `429` (honouring `Retry-After`) and concurrent-update `409`s with exponential backoff; on `401`, get a new token once and retry; don't retry other `4xx` without changing the request.
- Pagination: Most list endpoints return everything. `GET /api/v2/price-lists` pages with `page` and `page_size` (up to 250) until `pagination.current_page` equals `total_pages`. `GET /api/v1/purchases` uses `limit` (up to 500) and `offset`: stop when a page has fewer than `limit` results.
- Ground rules: Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer `GET /api/v2/price-lists` over the deprecated v1. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code.

Steps:
1. Read the price lists and prices (including any quantity price breaks) from my ERP.
2. Fetch every SparkLayer price list with `GET /api/v2/price-lists`, following the pagination.
3. Create any price list that exists in my ERP but not in SparkLayer with `POST /api/v1/price-lists`, as the Pricing API docs describe for price lists managed by an external system.
4. Send the prices for each price list with `PATCH /api/v1/price-lists/{slug}/pricing`, or several price lists at once with `PATCH /api/v1/batch-update-pricing`, matching products by SKU and keeping each request within the documented limits.
5. Record each run with the Sync Logging API: a full sync for a complete run, a partial sync for changes only.

Requirements:
- Keep credentials (Site ID, Client ID, Client Secret) in environment variables or a secrets manager, never in code.
- Cache the access token and request a new one shortly before it expires.
- Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409 responses with exponential backoff; on a 401, get a new token once and retry. Log every failed request with its status, `title` and `detail`.
- Make each run safe to repeat, so a failed run can simply be run again.
- Add a dry-run mode that logs what would change without calling the write endpoints.
- Only send prices that changed since the last successful run, if my ERP can tell me.
- Report SKUs that SparkLayer rejects, with the reason from the error response.
- Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing.

Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first.
```

### Keep stock levels in sync

Send stock levels per SKU and location from your ERP or WMS every few minutes.

```text
I want you to build a scheduled job that keeps SparkLayer stock levels in step with my stock system, using SparkLayer, the B2B ordering platform.
My setup: [describe your system, language and hosting]

Before writing any code, read these SparkLayer docs (Markdown versions):
- https://docs.sparklayer.io/developers/authentication.md: getting and using an access token
- https://docs.sparklayer.io/developers/api/stock.md: stock levels and stock locations
- https://docs.sparklayer.io/developers/api/stock/list-stock-locations.md: the stock locations SparkLayer knows about
- https://docs.sparklayer.io/developers/api/stock/update-stock-levels.md: updating stock for many SKUs in one call
- https://docs.sparklayer.io/developers/api/sync-log.md: recording each sync
- https://docs.sparklayer.io/developers/errors.md: error format and retries
If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation.

Facts that apply to every SparkLayer API call:
- Base URLs: Live `https://app.sparklayer.io`, test `https://test.app.sparklayer.io`. Each environment has its own data and its own API keys.
- Access: API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
- Access token: `POST {base}/api/auth/token` with a `Site-Id` header and a JSON body (not form-encoded): `{"grant_type":"client_credentials","client_id":"…","client_secret":"…"}`. It returns `access_token`, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires.
- Every request: `Authorization: Bearer <access_token>` and `Site-Id: <site id>`, plus `Content-Type: application/json` when there is a body. Set a `User-Agent` that names your integration.
- Errors: RFC 7807 problem details: `title`, `status`, `detail` and an optional `errors[]` of `{ code, message, property }`. Some error responses have no body. Retry `5xx`, `429` (honouring `Retry-After`) and concurrent-update `409`s with exponential backoff; on `401`, get a new token once and retry; don't retry other `4xx` without changing the request.
- Pagination: Most list endpoints return everything. `GET /api/v2/price-lists` pages with `page` and `page_size` (up to 250) until `pagination.current_page` equals `total_pages`. `GET /api/v1/purchases` uses `limit` (up to 500) and `offset`: stop when a page has fewer than `limit` results.
- Ground rules: Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer `GET /api/v2/price-lists` over the deprecated v1. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code.

Steps:
1. Read current stock levels per SKU (and per warehouse, if I have several) from my stock system.
2. Map my warehouses to SparkLayer stock locations from `GET /api/v1/stock-locations`, and tell me if any are missing rather than guessing.
3. Send the levels with `POST /api/v1/batch-update-stock`, matching products by SKU, in batches within the documented limits.
4. Record each run with the Sync Logging API.

Requirements:
- Keep credentials (Site ID, Client ID, Client Secret) in environment variables or a secrets manager, never in code.
- Cache the access token and request a new one shortly before it expires.
- Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409 responses with exponential backoff; on a 401, get a new token once and retry. Log every failed request with its status, `title` and `detail`.
- Make each run safe to repeat, so a failed run can simply be run again.
- Add a dry-run mode that logs what would change without calling the write endpoints.
- Send only SKUs whose stock changed since the last run, if my system can tell me.
- Never send a negative stock level unless the docs say it is allowed.
- Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing.

Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first.
```

### Send B2B orders to your ERP

Pick up new and updated B2B orders from SparkLayer and create them in your ERP.

```text
I want you to build a job that picks up new and updated B2B orders from SparkLayer and creates or updates them in my ERP, using SparkLayer, the B2B ordering platform.
My setup: [describe your system, language and hosting]

Before writing any code, read these SparkLayer docs (Markdown versions):
- https://docs.sparklayer.io/developers/authentication.md: getting and using an access token
- https://docs.sparklayer.io/developers/api/purchasing.md: what a purchase is and how orders, quotes and carts differ
- https://docs.sparklayer.io/developers/api/purchasing/get-purchases.md: listing orders with filters
- https://docs.sparklayer.io/developers/api/purchasing/get-purchase.md: fetching one order in full
- https://docs.sparklayer.io/developers/pagination.md: offset paging through purchases
- https://docs.sparklayer.io/developers/errors.md: error format and retries
If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation.

Facts that apply to every SparkLayer API call:
- Base URLs: Live `https://app.sparklayer.io`, test `https://test.app.sparklayer.io`. Each environment has its own data and its own API keys.
- Access: API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
- Access token: `POST {base}/api/auth/token` with a `Site-Id` header and a JSON body (not form-encoded): `{"grant_type":"client_credentials","client_id":"…","client_secret":"…"}`. It returns `access_token`, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires.
- Every request: `Authorization: Bearer <access_token>` and `Site-Id: <site id>`, plus `Content-Type: application/json` when there is a body. Set a `User-Agent` that names your integration.
- Errors: RFC 7807 problem details: `title`, `status`, `detail` and an optional `errors[]` of `{ code, message, property }`. Some error responses have no body. Retry `5xx`, `429` (honouring `Retry-After`) and concurrent-update `409`s with exponential backoff; on `401`, get a new token once and retry; don't retry other `4xx` without changing the request.
- Pagination: Most list endpoints return everything. `GET /api/v2/price-lists` pages with `page` and `page_size` (up to 250) until `pagination.current_page` equals `total_pages`. `GET /api/v1/purchases` uses `limit` (up to 500) and `offset`: stop when a page has fewer than `limit` results.
- Ground rules: Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer `GET /api/v2/price-lists` over the deprecated v1. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code.

Steps:
1. List orders with `GET /api/v1/purchases`, filtered to orders updated since the last successful run (use the documented date filters, not my own), paging with `limit` and `offset`.
2. Fetch each order in full if the list response lacks fields I need, and map it to my ERP's sales order format, including lines, prices, tax, shipping and the customer.
3. Create the order in my ERP, or update it if it was already sent, keyed on the SparkLayer order ID so nothing is created twice.
4. Store the timestamp of the last order processed and resume from it on the next run.

Requirements:
- Keep credentials (Site ID, Client ID, Client Secret) in environment variables or a secrets manager, never in code.
- Cache the access token and request a new one shortly before it expires.
- Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409 responses with exponential backoff; on a 401, get a new token once and retry. Log every failed request with its status, `title` and `detail`.
- Make each run safe to repeat, so a failed run can simply be run again.
- Add a dry-run mode that logs what would change without calling the write endpoints.
- Don't write anything back to SparkLayer unless the docs show an endpoint for it.
- Show me the field mapping as a table before writing the code.
- Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing.

Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first.
```

### Import order history

Load past orders from your ERP so B2B customers can see and reorder them.

```text
I want you to build a one-off import (that can be re-run safely) of historic orders from my system into SparkLayer, using SparkLayer, the B2B ordering platform.
My setup: [describe your system, language and hosting]

Before writing any code, read these SparkLayer docs (Markdown versions):
- https://docs.sparklayer.io/developers/authentication.md: getting and using an access token
- https://docs.sparklayer.io/developers/api/purchasing.md: purchases, identifiers and what customers see
- https://docs.sparklayer.io/developers/api/purchasing/create-update-purchase.md: creating or updating a purchase by your own ID
- https://docs.sparklayer.io/developers/api/purchasing/create-or-update-a-purchase-transaction.md: recording payments against a purchase
- https://docs.sparklayer.io/developers/errors.md: error format and retries
If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation.

Facts that apply to every SparkLayer API call:
- Base URLs: Live `https://app.sparklayer.io`, test `https://test.app.sparklayer.io`. Each environment has its own data and its own API keys.
- Access: API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
- Access token: `POST {base}/api/auth/token` with a `Site-Id` header and a JSON body (not form-encoded): `{"grant_type":"client_credentials","client_id":"…","client_secret":"…"}`. It returns `access_token`, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires.
- Every request: `Authorization: Bearer <access_token>` and `Site-Id: <site id>`, plus `Content-Type: application/json` when there is a body. Set a `User-Agent` that names your integration.
- Errors: RFC 7807 problem details: `title`, `status`, `detail` and an optional `errors[]` of `{ code, message, property }`. Some error responses have no body. Retry `5xx`, `429` (honouring `Retry-After`) and concurrent-update `409`s with exponential backoff; on `401`, get a new token once and retry; don't retry other `4xx` without changing the request.
- Pagination: Most list endpoints return everything. `GET /api/v2/price-lists` pages with `page` and `page_size` (up to 250) until `pagination.current_page` equals `total_pages`. `GET /api/v1/purchases` uses `limit` (up to 500) and `offset`: stop when a page has fewer than `limit` results.
- Ground rules: Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer `GET /api/v2/price-lists` over the deprecated v1. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code.

Steps:
1. Read my historic orders, their lines and their customers.
2. Create or update each one with `PUT /api/v1/purchases/{lookupBy}/{identifier}`, using my own order number as the identifier so running the import twice doesn't duplicate anything.
3. If my system has payments, record them with `PUT /api/v1/purchases/{lookupBy}/{identifier}/transactions`.
4. Write a report of orders that failed, with the reason.

Requirements:
- Keep credentials (Site ID, Client ID, Client Secret) in environment variables or a secrets manager, never in code.
- Cache the access token and request a new one shortly before it expires.
- Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409 responses with exponential backoff; on a 401, get a new token once and retry. Log every failed request with its status, `title` and `detail`.
- Make each run safe to repeat, so a failed run can simply be run again.
- Add a dry-run mode that logs what would change without calling the write endpoints.
- Process orders in batches and let me resume from where a run stopped.
- Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing.

Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first.
```

### Give key accounts their own prices

Create a price list per customer from your ERP contract prices, and check what a customer pays.

```text
I want you to build customer-specific prices from my ERP's contract prices, kept up to date, using SparkLayer, the B2B ordering platform.
My setup: [describe your system, language and hosting]

Before writing any code, read these SparkLayer docs (Markdown versions):
- https://docs.sparklayer.io/developers/authentication.md: getting and using an access token
- https://docs.sparklayer.io/developers/api/pricing.md: price lists, including customer-specific ones
- https://docs.sparklayer.io/help/pricing/customer-pricing.md: how a price list is linked to one customer on each platform
- https://docs.sparklayer.io/developers/api/pricing/create-a-price-list.md: creating a price list
- https://docs.sparklayer.io/developers/api/pricing/update-pricing-by-price-list.md: setting its prices
- https://docs.sparklayer.io/developers/api/core/get-customer-specific-pricing.md: checking the prices a customer gets
- https://docs.sparklayer.io/developers/errors.md: error format and retries
If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation.

Facts that apply to every SparkLayer API call:
- Base URLs: Live `https://app.sparklayer.io`, test `https://test.app.sparklayer.io`. Each environment has its own data and its own API keys.
- Access: API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
- Access token: `POST {base}/api/auth/token` with a `Site-Id` header and a JSON body (not form-encoded): `{"grant_type":"client_credentials","client_id":"…","client_secret":"…"}`. It returns `access_token`, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires.
- Every request: `Authorization: Bearer <access_token>` and `Site-Id: <site id>`, plus `Content-Type: application/json` when there is a body. Set a `User-Agent` that names your integration.
- Errors: RFC 7807 problem details: `title`, `status`, `detail` and an optional `errors[]` of `{ code, message, property }`. Some error responses have no body. Retry `5xx`, `429` (honouring `Retry-After`) and concurrent-update `409`s with exponential backoff; on `401`, get a new token once and retry; don't retry other `4xx` without changing the request.
- Pagination: Most list endpoints return everything. `GET /api/v2/price-lists` pages with `page` and `page_size` (up to 250) until `pagination.current_page` equals `total_pages`. `GET /api/v1/purchases` uses `limit` (up to 500) and `offset`: stop when a page has fewer than `limit` results.
- Ground rules: Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer `GET /api/v2/price-lists` over the deprecated v1. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code.

Steps:
1. For each customer with contract prices in my ERP, create (or reuse) a price list for them and send its prices by SKU.
2. Link the price list to the customer the way the docs describe for my eCommerce platform. If that step can't be done through the API, tell me exactly what to set up instead.
3. Check the result for a sample customer with `POST /api/v1/fetch-customer-pricing`.

Requirements:
- Keep credentials (Site ID, Client ID, Client Secret) in environment variables or a secrets manager, never in code.
- Cache the access token and request a new one shortly before it expires.
- Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409 responses with exponential backoff; on a 401, get a new token once and retry. Log every failed request with its status, `title` and `detail`.
- Make each run safe to repeat, so a failed run can simply be run again.
- Add a dry-run mode that logs what would change without calling the write endpoints.
- Name price lists so each one clearly maps to its customer.
- Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing.

Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first.
```

### Upload invoices and documents

Attach invoices, certificates and other files so B2B customers can download them.

```text
I want you to build a job that uploads documents from my system to SparkLayer so customers can see them, using SparkLayer, the B2B ordering platform.
My setup: [describe your system, language and hosting]

Before writing any code, read these SparkLayer docs (Markdown versions):
- https://docs.sparklayer.io/developers/authentication.md: getting and using an access token
- https://docs.sparklayer.io/developers/api/files.md: how files, uploads and metadata work
- https://docs.sparklayer.io/developers/api/files/create-a-new-file.md: creating a file and getting its upload URL
- https://docs.sparklayer.io/developers/api/files/query-files-by-metadata.md: finding files you already uploaded
- https://docs.sparklayer.io/developers/errors.md: error format and retries
If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation.

Facts that apply to every SparkLayer API call:
- Base URLs: Live `https://app.sparklayer.io`, test `https://test.app.sparklayer.io`. Each environment has its own data and its own API keys.
- Access: API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
- Access token: `POST {base}/api/auth/token` with a `Site-Id` header and a JSON body (not form-encoded): `{"grant_type":"client_credentials","client_id":"…","client_secret":"…"}`. It returns `access_token`, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires.
- Every request: `Authorization: Bearer <access_token>` and `Site-Id: <site id>`, plus `Content-Type: application/json` when there is a body. Set a `User-Agent` that names your integration.
- Errors: RFC 7807 problem details: `title`, `status`, `detail` and an optional `errors[]` of `{ code, message, property }`. Some error responses have no body. Retry `5xx`, `429` (honouring `Retry-After`) and concurrent-update `409`s with exponential backoff; on `401`, get a new token once and retry; don't retry other `4xx` without changing the request.
- Pagination: Most list endpoints return everything. `GET /api/v2/price-lists` pages with `page` and `page_size` (up to 250) until `pagination.current_page` equals `total_pages`. `GET /api/v1/purchases` uses `limit` (up to 500) and `offset`: stop when a page has fewer than `limit` results.
- Ground rules: Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer `GET /api/v2/price-lists` over the deprecated v1. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code.

Steps:
1. For each new document, create the file with `POST /api/v1/files`, with the metadata the docs describe for linking it to a customer or order.
2. Upload the file to the URL that response returns, exactly as the Files API docs describe.
3. Before uploading, check by metadata whether the document already exists, so nothing is uploaded twice.

Requirements:
- Keep credentials (Site ID, Client ID, Client Secret) in environment variables or a secrets manager, never in code.
- Cache the access token and request a new one shortly before it expires.
- Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409 responses with exponential backoff; on a 401, get a new token once and retry. Log every failed request with its status, `title` and `detail`.
- Make each run safe to repeat, so a failed run can simply be run again.
- Add a dry-run mode that logs what would change without calling the write endpoints.
- Handle files that fail SparkLayer's checks after upload (see the `410` status in the errors guide).
- Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing.

Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first.
```

### Build a headless B2B storefront

Use the JavaScript SDK in your own frontend for B2B prices, cart and account.

```text
I want you to build B2B pricing, cart and account features in my own frontend with the SparkLayer JavaScript SDK, using SparkLayer, the B2B ordering platform.
My setup: [describe your system, language and hosting]

Before writing any code, read these SparkLayer docs (Markdown versions):
- https://docs.sparklayer.io/developers/javascript-sdk.md: what the SDK does
- https://docs.sparklayer.io/developers/javascript-sdk/headless.md: loading and initialising the SDK yourself
- https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md: every SDK method
- https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md: every option
- https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md: reacting to cart changes
- https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md: showing B2B prices, price breaks and pack sizes
- https://docs.sparklayer.io/developers/javascript-sdk/cart.md: adding to and reading the cart
- https://docs.sparklayer.io/developers/frontend.md: the Core Script and where it is configured
If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation.

Steps:
1. Load and initialise the SDK as the headless guide describes, once, on the client only.
2. Show B2B prices on product pages with the documented pricing methods, including price breaks and pack sizes.
3. Add to cart and read the cart with the documented cart methods, and react to cart changes with the `onCartUpdate` hook.
4. Wrap the SDK in a small typed module for my framework, waiting for it to be ready before calling it.

Requirements:
- Use only the SDK methods, options and hooks in the reference.
- Prefer documented options, hooks and custom slots. Customising SparkLayer's own components is fine too: keep HTML changes targeted and note what to check after SparkLayer updates.
- Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing.

Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first.
```

### Add a custom checkout rule

Block checkout until the cart meets your own rule, with a clear message.

```text
I want you to build a custom checkout validation rule using the SparkLayer JavaScript SDK, using SparkLayer, the B2B ordering platform.
My setup: [describe your system, language and hosting]

Before writing any code, read these SparkLayer docs (Markdown versions):
- https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md: the `onCheckoutValidation` hook
- https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md: the cart types
- https://docs.sparklayer.io/developers/javascript-sdk/checkout.md: working checkout validation examples
- https://docs.sparklayer.io/developers/javascript-sdk/setup.md: adding hooks without overwriting existing options
- https://docs.sparklayer.io/help/storefront/storefront-options.md: where Core Script settings go
If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation.

Steps:
1. Implement the rule in the `onCheckoutValidation` hook, returning the documented error format.
2. Show customers a clear message that explains how to fix their cart.
3. Add the code to my theme in the place the docs describe, without overwriting existing `sparkOptions`.

Requirements:
- Keep the hook fast: avoid network calls on every check unless the rule needs them.
- Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing.

Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first.
```

### Connect a new platform with Ignite

Build the service that connects an unsupported commerce platform to SparkLayer.

```text
I want you to build an Ignite integration service that connects my commerce platform to SparkLayer, using SparkLayer, the B2B ordering platform.
My setup: [describe your system, language and hosting]

Before writing any code, read these SparkLayer docs (Markdown versions):
- https://docs.sparklayer.io/ignite.md: what Ignite is and how the pieces fit
- https://docs.sparklayer.io/ignite/platform-connection.md: connecting a store
- https://docs.sparklayer.io/ignite/authentication.md: customer authentication
- https://docs.sparklayer.io/ignite/data-sync.md: syncing products, customers and orders
- https://docs.sparklayer.io/ignite/endpoints-overview.md: every endpoint your service implements
If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation.

Facts that apply to every SparkLayer API call:
- Base URLs: Live `https://app.sparklayer.io`, test `https://test.app.sparklayer.io`. Each environment has its own data and its own API keys.
- Access: API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
- Access token: `POST {base}/api/auth/token` with a `Site-Id` header and a JSON body (not form-encoded): `{"grant_type":"client_credentials","client_id":"…","client_secret":"…"}`. It returns `access_token`, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires.
- Every request: `Authorization: Bearer <access_token>` and `Site-Id: <site id>`, plus `Content-Type: application/json` when there is a body. Set a `User-Agent` that names your integration.
- Errors: RFC 7807 problem details: `title`, `status`, `detail` and an optional `errors[]` of `{ code, message, property }`. Some error responses have no body. Retry `5xx`, `429` (honouring `Retry-After`) and concurrent-update `409`s with exponential backoff; on `401`, get a new token once and retry; don't retry other `4xx` without changing the request.
- Pagination: Most list endpoints return everything. `GET /api/v2/price-lists` pages with `page` and `page_size` (up to 250) until `pagination.current_page` equals `total_pages`. `GET /api/v1/purchases` uses `limit` (up to 500) and `offset`: stop when a page has fewer than `limit` results.
- Ground rules: Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer `GET /api/v2/price-lists` over the deprecated v1. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code.

Steps:
1. Implement the endpoints in the Ignite spec (https://docs.sparklayer.io/openapi/ignite.yaml) that my platform needs, starting with the platform connection and authentication.
2. Implement data sync for products, customers and orders as the Ignite docs describe.
3. Implement checkout: calculating tax and shipping, and completing the checkout on my platform.
4. Write integration tests for each endpoint with example requests from the spec.

Requirements:
- Keep credentials (Site ID, Client ID, Client Secret) in environment variables or a secrets manager, never in code.
- Cache the access token and request a new one shortly before it expires.
- Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409 responses with exponential backoff; on a 401, get a new token once and retry. Log every failed request with its status, `title` and `detail`.
- Make each run safe to repeat, so a failed run can simply be run again.
- Add a dry-run mode that logs what would change without calling the write endpoints.
- Where the docs leave something open (for example how SparkLayer authenticates its calls to your service), list it as a question for SparkLayer rather than assuming.
- Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing.

Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first.
```

Each prompt asks the assistant to start with questions and a plan, and to test against the SparkLayer [test environment](https://docs.sparklayer.io/developers/authentication.md#environments) first. Review the code before you run it on your live store.

## Point any assistant at the docs

Paste one of these links into your assistant, or add it to your tool's documentation sources:

| Resource | What's in it | Link |
| --- | --- | --- |
| Any page, as Markdown | Add `.md` to a page's URL, or request it with `Accept: text/markdown` | [/developers/quickstart.md](https://docs.sparklayer.io/developers/quickstart.md) |
| `llms.txt` | Every page with a one-line summary, plus the facts below | [/llms.txt](https://docs.sparklayer.io/llms.txt) |
| API index | Every API operation, compactly, with links to each operation | [/llms-api.txt](https://docs.sparklayer.io/llms-api.txt) |
| Developer docs | The developer guides in full, with the API index | [/developers/llms.txt](https://docs.sparklayer.io/developers/llms.txt) |
| OpenAPI specs | One spec per API, in YAML and JSON, for code generation and tools. The index lists them all | `https://docs.sparklayer.io/openapi/index.json` |

Developer pages also open with a **For AI assistants** panel: the facts below, so an assistant gets them from whichever page you share.

## The facts your assistant needs

These apply to every SparkLayer API call. They come from [Authentication](https://docs.sparklayer.io/developers/authentication.md), [Errors](https://docs.sparklayer.io/developers/errors.md) and [Pagination](https://docs.sparklayer.io/developers/pagination.md).

- **Base URLs:** Live `https://app.sparklayer.io`, test `https://test.app.sparklayer.io`. Each environment has its own data and its own API keys.
- **Access:** API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
- **Access token:** `POST {base}/api/auth/token` with a `Site-Id` header and a JSON body (not form-encoded): `{"grant_type":"client_credentials","client_id":"…","client_secret":"…"}`. It returns `access_token`, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires.
- **Every request:** `Authorization: Bearer <access_token>` and `Site-Id: <site id>`, plus `Content-Type: application/json` when there is a body. Set a `User-Agent` that names your integration.
- **Errors:** RFC 7807 problem details: `title`, `status`, `detail` and an optional `errors[]` of `{ code, message, property }`. Some error responses have no body. Retry `5xx`, `429` (honouring `Retry-After`) and concurrent-update `409`s with exponential backoff; on `401`, get a new token once and retry; don't retry other `4xx` without changing the request.
- **Pagination:** Most list endpoints return everything. `GET /api/v2/price-lists` pages with `page` and `page_size` (up to 250) until `pagination.current_page` equals `total_pages`. `GET /api/v1/purchases` uses `limit` (up to 500) and `offset`: stop when a page has fewer than `limit` results.
- **Ground rules:** Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer `GET /api/v2/price-lists` over the deprecated v1. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code.
- **Read the docs as Markdown:** Add `.md` to any page URL. Index of every page: https://docs.sparklayer.io/llms.txt. Every API operation, compactly: https://docs.sparklayer.io/llms-api.txt. The developer guides in full: https://docs.sparklayer.io/developers/llms.txt.
- **OpenAPI specs:** `core`, `ordering`, `pricing`, `purchasing`, `stock`, `files`, `sync-log`: https://docs.sparklayer.io/openapi/<api>.yaml (also `.json`). Ignite: https://docs.sparklayer.io/openapi/ignite.yaml.
- **MCP:** Search and read these docs from your assistant with the docs MCP server at https://docs.sparklayer.io/mcp.

## Connect the docs MCP server

The docs MCP server lets an assistant search these docs, read any page and look up API operations while it writes your code. It's free, read-only and needs no account. The server URL is:

```text title="MCP server"
https://docs.sparklayer.io/mcp
```

**Claude Code:**

Run this once in your project:

```bash title="Terminal"
claude mcp add --transport http sparklayer-docs https://docs.sparklayer.io/mcp
```

**Claude:**

In Claude, open **Settings** > **Connectors**, choose **Add custom connector**, and enter the server URL. Then turn the connector on in your chat.

**Cursor:**

Add the server to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for every project):

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "sparklayer-docs": {
      "url": "https://docs.sparklayer.io/mcp"
    }
  }
}
```

**VS Code:**

Add the server to `.vscode/mcp.json` in your project, then start it from the file:

```json title=".vscode/mcp.json"
{
  "servers": {
    "sparklayer-docs": {
      "type": "http",
      "url": "https://docs.sparklayer.io/mcp"
    }
  }
}
```

**ChatGPT:**

In ChatGPT, add a connector with the server URL from **Settings** > **Apps & Connectors**. Custom connectors need developer mode, which your workspace admin may need to turn on.

The server has tools to search the docs, read a page, list pages, and look up API operations and specs. Your assistant decides when to use them.

## Get better results

- **Start in the test environment.** Create an API key in [Test mode](https://docs.sparklayer.io/developers/authentication.md#environments) and point your code at `https://test.app.sparklayer.io` until it works.
- **Ask for a plan first.** A short plan and field mapping are quicker to correct than finished code.
- **Generate types from the specs.** Tools such as `openapi-typescript` or `openapi-generator` turn the OpenAPI specs (listed at `https://docs.sparklayer.io/openapi/index.json`) into typed clients, so your assistant can't invent fields.
- **Keep credentials out of chats.** Give the assistant variable names, such as `SPARKLAYER_CLIENT_SECRET`, never the real values.
- **Check against the reference.** If an assistant uses an endpoint or field you can't find in the [API reference](https://docs.sparklayer.io/developers/api.md), ask it where it came from.

## Next steps

- [Quickstart](https://docs.sparklayer.io/developers/quickstart.md): Make your first API call in five minutes
- [API reference](https://docs.sparklayer.io/developers/api.md): Every endpoint, with examples
- [JavaScript SDK](https://docs.sparklayer.io/developers/javascript-sdk.md): Storefront examples to start from, and a prompt for SDK work


---

# Authentication

URL: https://docs.sparklayer.io/developers/authentication

Authenticate with the SparkLayer APIs using OAuth 2.0 client credentials: request a Bearer token from /api/auth/token and send it with your Site-Id header.

Every request to the SparkLayer APIs needs an access token. Getting one takes three steps:

1. Create an API key in the SparkLayer Dashboard.
2. Swap the key's client ID and secret for an access token, which lasts an hour.
3. Send the token with every request.

This is the standard OAuth 2.0 client credentials flow.

For a step-by-step first call, see the [quickstart](https://docs.sparklayer.io/developers/quickstart.md).

## Environments

Each SparkLayer account has a live environment and, on plans with [Test mode](https://docs.sparklayer.io/help/dashboard/test-mode.md), a test environment. The host you call selects the environment:

| Environment | Base URL |
| --- | --- |
| Live | `https://app.sparklayer.io` |
| Test | `https://test.app.sparklayer.io` |

The environments hold separate data and separate API keys. A key created while the Dashboard is in Test mode only works against the test base URL, and a key created in live mode only works against the live base URL.

## Create an API key

**Step 1.** **Open the API settings**

In the SparkLayer Dashboard, go to **Settings > API** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/api)), or **SparkLayer Wholesale > Settings > API** in the Shopify app. Turn on **Test mode** first if you want a key for the test environment.

**Step 2.** **Create a key**

Select **Create new API Key** and give the key a name that identifies the integration using it.

**Step 3.** **Copy the credentials**

Copy the **Site ID**, **Client ID** and **Client Secret**. The client secret is only shown once, so store it securely — for example in your integration's secrets manager.

Deleting a key in the Dashboard also revokes every access token issued for it.

## Request an access token

Send a `POST` request to `/api/auth/token` with your Site ID in the `Site-Id` header and your credentials in a JSON body. The token endpoint only accepts `Content-Type: application/json`:

```bash
curl -X POST https://app.sparklayer.io/api/auth/token \
  -H "Site-Id: <SITE_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "<CLIENT_ID>",
    "client_secret": "<CLIENT_SECRET>"
  }'
```

| Field | Value |
| --- | --- |
| `grant_type` | Always `client_credentials` |
| `client_id` | The Client ID shown when you created the key |
| `client_secret` | The Client Secret shown when you created the key |

If the credentials are valid, you receive an access token:

```json
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "<ACCESS_TOKEN>"
}
```

| Field | Description |
| --- | --- |
| `token_type` | Always `Bearer` |
| `expires_in` | Seconds until the token expires: tokens are valid for 1 hour |
| `access_token` | The token to send in the `Authorization` header |

A token only works with the Site ID and environment it was issued for. No refresh token is issued: when a token expires, request a new one with the same credentials.

> **Standard OAuth libraries won't work as they are**
>
> The token request is JSON with a `Site-Id` header, not the form-encoded body most OAuth 2.0 client libraries send. Request the token with a plain HTTP call, as below, or configure your library to send JSON and the extra header.

## Call the API

Send the token in the `Authorization` header, together with the `Site-Id` header, on every request:

```bash
curl "https://app.sparklayer.io/api/v2/price-lists" \
  -H "Site-Id: <SITE_ID>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "User-Agent: acme-erp-sync/1.2"
```

| Header | Value |
| --- | --- |
| `Site-Id` | Your Site ID |
| `Authorization` | `Bearer <ACCESS_TOKEN>` |
| `Content-Type` | `application/json` for requests with a body |

> **Set a User-Agent**
>
> Set a `User-Agent` header that identifies your integration, such as `acme-erp-sync/1.2`. It helps our support team find your requests if you need help debugging an issue.

## Reuse the access token

Request a token once and reuse it for every call until it's close to expiry, rather than requesting one per call. These small helpers do that, and fetch a new token when one is rejected:

**Node.js:**

```javascript title="sparklayer.mjs"
const { SPARKLAYER_BASE_URL, SPARKLAYER_SITE_ID, SPARKLAYER_CLIENT_ID, SPARKLAYER_CLIENT_SECRET } =
  process.env;

let token = null; // { value, expiresAt }

async function getToken() {
  // reuse the token until a minute before it expires
  if (token && Date.now() < token.expiresAt - 60_000) return token.value;
  const response = await fetch(`${SPARKLAYER_BASE_URL}/api/auth/token`, {
    method: 'POST',
    headers: { 'Site-Id': SPARKLAYER_SITE_ID, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'client_credentials',
      client_id: SPARKLAYER_CLIENT_ID,
      client_secret: SPARKLAYER_CLIENT_SECRET,
    }),
  });
  if (!response.ok) throw new Error(`Token request failed: ${response.status}`);
  const body = await response.json();
  token = { value: body.access_token, expiresAt: Date.now() + body.expires_in * 1000 };
  return token.value;
}

/** Calls a SparkLayer API path, e.g. sparklayer('/api/v2/price-lists'). */
export async function sparklayer(path, init = {}, retried = false) {
  const response = await fetch(`${SPARKLAYER_BASE_URL}${path}`, {
    ...init,
    headers: {
      'Site-Id': SPARKLAYER_SITE_ID,
      Authorization: `Bearer ${await getToken()}`,
      'User-Agent': 'acme-erp-sync/1.2',
      ...(init.body ? { 'Content-Type': 'application/json' } : {}),
      ...init.headers,
    },
  });
  if (response.status === 401 && !retried) {
    token = null; // the token was rejected: get a new one and try once more
    return sparklayer(path, init, true);
  }
  return response;
}
```

**Python:**

```python title="sparklayer.py"
import os
import time

import requests

BASE_URL = os.environ["SPARKLAYER_BASE_URL"]
SITE_ID = os.environ["SPARKLAYER_SITE_ID"]
_token = {"value": None, "expires_at": 0.0}

def get_token() -> str:
    # reuse the token until a minute before it expires
    if _token["value"] and time.time() < _token["expires_at"] - 60:
        return _token["value"]
    response = requests.post(
        f"{BASE_URL}/api/auth/token",
        headers={"Site-Id": SITE_ID},
        json={
            "grant_type": "client_credentials",
            "client_id": os.environ["SPARKLAYER_CLIENT_ID"],
            "client_secret": os.environ["SPARKLAYER_CLIENT_SECRET"],
        },
        timeout=30,
    )
    response.raise_for_status()
    body = response.json()
    _token.update(value=body["access_token"], expires_at=time.time() + body["expires_in"])
    return _token["value"]

def sparklayer(method: str, path: str, retried: bool = False, **kwargs) -> requests.Response:
    """Calls a SparkLayer API path, e.g. sparklayer("GET", "/api/v2/price-lists")."""
    headers = {
        "Site-Id": SITE_ID,
        "Authorization": f"Bearer {get_token()}",
        "User-Agent": "acme-erp-sync/1.2",
        **kwargs.pop("headers", {}),
    }
    response = requests.request(method, f"{BASE_URL}{path}", headers=headers, timeout=60, **kwargs)
    if response.status_code == 401 and not retried:
        _token["value"] = None  # the token was rejected: get a new one and try once more
        return sparklayer(method, path, retried=True, **kwargs)
    return response
```

For retries on other errors, see [Retrying requests](https://docs.sparklayer.io/developers/errors.md#retrying-requests).

## Authentication errors

If authentication fails, the API responds with a JSON error body. See [Errors](https://docs.sparklayer.io/developers/errors.md) for the format and every status code.

| Status | When |
| --- | --- |
| `400` | The token request is missing the `Site-Id` header, a required field or `Content-Type: application/json` |
| `401` | The client ID or secret is wrong, or the access token is missing, invalid or expired |
| `401` or `403` | The access token was issued for a different Site ID or environment. The Pricing and Purchasing APIs also return `403` when the `Authorization` header is missing |


---

# Errors

URL: https://docs.sparklayer.io/developers/errors

HTTP status codes the SparkLayer APIs return, the JSON error body and its fields, validation error details, and which errors you can safely retry.

The SparkLayer APIs use standard HTTP status codes: `2xx` for success, `4xx` when the request needs fixing, and `5xx` when something went wrong on SparkLayer's side. Most errors include a JSON body that explains the problem.

## Error body

Error bodies follow the [RFC 7807 problem details](https://www.rfc-editor.org/rfc/rfc7807) format:

```json
{
  "title": "invalid-request-contents",
  "status": 400,
  "detail": "Unable to validate request contents",
  "errors": [
    {
      "code": "keyword-mismatch",
      "message": "<what is wrong with the value>",
      "property": "customer_id"
    }
  ]
}
```

| Field | Description |
| --- | --- |
| `title` | A short identifier for the type of problem, such as `invalid-request-contents` or `resource-not-found` |
| `status` | The HTTP status code, repeated for convenience |
| `detail` | A human-readable explanation. Use it for logging and debugging, not to drive your integration's logic |
| `errors` | Optional. A list of individual problems, each with a machine-readable `code`, a `message` and, where relevant, the `property` it applies to |

Some APIs also include `"type": "about:blank"`. Treat the status code as the primary signal, `title` and `errors[].code` as more specific detail, and ignore fields you don't recognise.

> **Differences between APIs**
>
> The APIs are separate services, so some responses differ in detail:
>
> - Errors are `application/problem+json`, except the cart's **Calculate** and **Complete** validation errors (`422`), which are plain `application/json` with their own `cart-error` and `cart-validation-errors` shapes.
> - Invalid price updates sent to the [Pricing API](https://docs.sparklayer.io/developers/api/pricing.md) (for example with **Update prices in a price list**) return a `400` whose body is a list of `{ "line", "field", "message" }` objects, so you can match each problem to a row of your JSON array or CSV file.
> - Some responses, such as a `404` for an unknown route, a `405`, a `415` or an unexpected `500`, can have an empty body.
> - The endpoint pages in the API reference list the responses each operation returns.

## Status codes

| Status | Meaning | What to do |
| --- | --- | --- |
| `200`, `201`, `204` | Success. `204` responses have no body | — |
| `207` | Partial success: some items in the request couldn't be processed, and each affected item carries an error. Returned by **Get customer-specific pricing** | Check each item for an error |
| `400` | The request is invalid: the body, parameters or headers (including `Site-Id`) don't match the API's schema, a required value is missing, or the request breaks a business rule | Fix the request using `detail` and `errors`. Don't retry it unchanged |
| `401` | The access token is missing, malformed or expired, or was issued for a different site or environment. On `/api/auth/token`, the client ID or secret is wrong | Request a new access token, then retry. See [Authentication](https://docs.sparklayer.io/developers/authentication.md) |
| `403` | The request isn't allowed. The Pricing and Purchasing APIs also return `403` when the `Authorization` header is missing, or the token was issued for a different site or environment | Check the `Authorization` and `Site-Id` headers, and that you're using credentials for the right environment |
| `404` | The resource or route doesn't exist | Check the ID, slug or `lookupBy` value and the URL |
| `405` | The endpoint exists but doesn't support the HTTP method | Check the method in the API reference |
| `409` | The request conflicts with existing data — for example a duplicate external ID, a newer version of the record already exists, or another update to the same data was running at the same time | Fetch the current state, resolve the conflict and retry |
| `410` | The resource is gone — for example a file that failed its checks after upload | Don't retry. Upload the file again |
| `415` | The `Content-Type` header isn't supported by the endpoint | Send `Content-Type: application/json` (the Pricing API also accepts `text/csv` on some endpoints) |
| `422` | The Ordering API can't process the cart — for example it's empty, or it has validation errors when you try to complete it | See [Cart errors](#cart-errors) |
| `500` | An unexpected error on SparkLayer's side | Retry with exponential backoff. If it persists, check the [status page](https://status.sparklayer.io/), then [contact support](https://docs.sparklayer.io/help/support.md) with the request details |
| `502`, `503`, `504` | The service is temporarily unavailable or took too long to respond | Retry with exponential backoff. If they continue, check the [status page](https://status.sparklayer.io/) for an incident |

## Authentication errors

Errors from `/api/auth/token`, and errors caused by a missing or invalid token on the Core and Ordering APIs, use [OAuth 2.0 error codes](https://www.rfc-editor.org/rfc/rfc6749#section-5.2) as the `title`:

```json
{
  "title": "invalid_client",
  "status": 401,
  "detail": "Client authentication failed"
}
```

| `title` | Status | Cause |
| --- | --- | --- |
| `invalid_client` | `401` | The client ID or secret is wrong, the key has been deleted, or it belongs to the other environment |
| `invalid_request` | `400` | A required field, such as `client_secret`, is missing |
| `unsupported_grant_type` | `400` | `grant_type` isn't `client_credentials` |
| `access_denied` | `401` | The `Authorization` header is missing, or the token is invalid, expired or for another site or environment |

The Pricing, Purchasing, Stock, Sync Logging and Files APIs return a `401` or `403` problem body with a `detail` explaining why the token was rejected.

## Validation errors

When a request doesn't match the API's schema, the response is a `400` with details of each problem in `errors`. On the Core and Ordering APIs, and for most requests to the Pricing API, the `title` is `invalid-request-contents`. The Core and Ordering APIs use these codes:

| `code` | Cause |
| --- | --- |
| `keyword-mismatch` | A value breaks a schema rule, such as a type, format or length. `property` points to it |
| `body-mismatch` | The body isn't valid JSON or doesn't match the expected shape |
| `headers-mismatch` | A required header, such as `Site-Id` or `Content-Type`, is missing or invalid |
| `parameters-mismatch` | A path or query parameter is invalid, such as an unsupported `lookupBy` value |
| `path-mismatch` | The path doesn't match the endpoint |
| `missing-param` | A required value is missing |
| `resource-already-exists` | A value that must be unique, such as a slug, is already in use |
| `resource-id-not-found` | An ID or slug in the request doesn't match an existing resource |
| `resource-id-invalid` | An ID isn't in the expected format |
| `resource-in-use` | The resource can't be deleted because something else uses it |

The Purchasing, Stock, Sync Logging and Files APIs describe schema problems in `detail` instead.

## Cart errors

The [Ordering API](https://docs.sparklayer.io/developers/api/ordering.md) returns `422` when it can't process a cart. The `title` tells you which kind of problem it is:

- `cart-error`: `errors` lists codes such as `cart-empty`, `cart-customer-not-found`, `cart-shipping-rate-handle-unavailable` or `cart-payment-method-unavailable`.
- `cart-validation-errors`: returned by **Complete a cart** when the cart has validation errors you haven't chosen to ignore. `errors.validation_error_types` lists them. Fix the cart, or list the types you accept in `ignore_validation_errors`, and try again.

## Retrying requests

- Retry `5xx` responses and `409` conflicts caused by concurrent updates, using exponential backoff.
- On a `401`, request a new access token once and retry. If it fails again, check your credentials rather than retrying.
- Don't retry other `4xx` responses without changing the request.
- `PUT` requests that create or replace a record, such as **Create or update a purchase**, are safe to repeat. Before retrying a `POST` that creates something, check whether the first attempt succeeded.

## Rate limits

SparkLayer doesn't publish fixed rate limits. Design your integration to be gentle and to recover:

- Send changes in batches using the bulk endpoints (for example **Update prices across price lists** and **Update stock levels for multiple SKUs**) rather than one request per SKU.
- Run requests one after another, or with a small number in parallel.
- No SparkLayer API returns `429 Too Many Requests` today. If you ever receive one, wait before retrying: use the `Retry-After` header if the response has one, otherwise back off exponentially.


---

# Pagination

URL: https://docs.sparklayer.io/developers/pagination

Page through large result sets in the SparkLayer APIs: page-based pagination for price lists, offset paging for purchases, and which lists return everything.

Most SparkLayer list endpoints return every matching record in a single response. Two endpoint families paginate, each with its own pattern.

## Page-based: price lists

`GET /api/v2/price-lists` and `GET /api/v2/price-lists-num-manual-prices` in the [Pricing API](https://docs.sparklayer.io/developers/api/pricing.md) return results one page at a time.

| Query parameter | Default | Description |
| --- | --- | --- |
| `page` | `1` | The page to return |
| `page_size` | `100` | Records per page, up to `250` |
| `order_by` | `name:asc` | Sort field and direction: `name`, `created_at` or `updated_at`, followed by `:asc` or `:desc` |

The response wraps the records in `data`, with a `pagination` object:

```json
{
  "data": [ … ],
  "pagination": {
    "total": 312,
    "per_page": 100,
    "current_page": 1,
    "total_pages": 4
  }
}
```

Request pages until `current_page` equals `total_pages`:

```bash
curl "https://app.sparklayer.io/api/v2/price-lists?page=2&page_size=100" \
  -H "Site-Id: <SITE_ID>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
```

> **Use v2 for price lists**
>
> `GET /api/v1/price-lists` is the older, unpaginated version of this endpoint: it returns up to 25,000 price lists in one array. Use `GET /api/v2/price-lists` for new integrations.

## Offset-based: purchases

`GET /api/v1/purchases` in the [Purchasing API](https://docs.sparklayer.io/developers/api/purchasing.md) uses a limit and an offset.

| Query parameter | Default | Description |
| --- | --- | --- |
| `limit` | Not set | Maximum number of purchases to return, from `1` to `500`. Always set it. |
| `offset` | `0` | Number of purchases to skip |
| `order_by` | `created_at` | Field to sort by, always newest first: `created_at`, `updated_at`, `placed_at`, `calculated_submitted_at` or `shipping_requested_date` |

The response is a plain array with no total count. To fetch every purchase, increase `offset` by `limit` after each request, and stop when a response contains fewer than `limit` purchases:

```bash
curl "https://app.sparklayer.io/api/v1/purchases?type=order&limit=500&offset=500" \
  -H "Site-Id: <SITE_ID>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
```

Keep `order_by` and any filters the same for every page. Records created or updated while you're paging can shift between pages, so use a date filter such as `dates[last_updated][gte]` for incremental syncs.

## Endpoints that aren't paginated

Other list endpoints return all matching records in one response, including the Core API's customer groups, discounts, shipping methods and settings, and the Stock API's stock locations. A few have a fixed upper limit:

- **List sync errors** in the [Sync Logging API](https://docs.sparklayer.io/developers/api/sync-log.md) returns at most 5,000 errors.
- **List price lists** (v1) returns at most 25,000 price lists.


---

# SparkLayer API

URL: https://docs.sparklayer.io/developers/api

Overview of the SparkLayer REST APIs: what each API covers, base URLs for live and test, authentication, request format and which plans include access.

The SparkLayer API is a set of REST APIs that connect your backend systems, such as an ERP, CRM or [iPaaS](https://docs.sparklayer.io/help/glossary.md#ipaas), to SparkLayer. Use them to send B2B data like price lists and stock levels, keep order history in step, and manage how customers buy.

> **Plan requirement**
>
> API access is available on the [Pro and Enterprise plans](https://www.sparklayer.io/pricing/).

## Which APIs you need

Most integrations need only one or two of these APIs.

- **On a platform SparkLayer integrates with, such as [Shopify](https://docs.sparklayer.io/help/platforms/shopify.md)?** SparkLayer already gets your products and customers from the platform. Start with the Pricing API, and add the Stock and Purchasing APIs if your ERP holds stock levels and order history.
- **On a platform SparkLayer doesn't integrate with?** Use [Ignite](#ignite) to connect it.

If you're not sure which approach suits your integration, [contact our support team](https://docs.sparklayer.io/help/support.md) to talk it through.

## The APIs

| API | Use it to |
| --- | --- |
| [Pricing API](https://docs.sparklayer.io/developers/api/pricing.md) | Create price lists, set prices by SKU and calculate the price a customer pays |
| [Stock API](https://docs.sparklayer.io/developers/api/stock.md) | Read, update and delete stock levels by SKU, and manage stock locations |
| [Purchasing API](https://docs.sparklayer.io/developers/api/purchasing.md) | Keep the orders, quotes and carts customers see in My Account, with their history and payments |
| [Ordering API](https://docs.sparklayer.io/developers/api/ordering.md) | Build a cart for a customer, price it, and place it as an order on your eCommerce platform |
| [Core API](https://docs.sparklayer.io/developers/api/core.md) | Manage customer groups, discounts, shipping methods and settings, delete customers, and look up a customer's prices |
| [Files API](https://docs.sparklayer.io/developers/api/files.md) | Upload and download files, such as the attachments customers add to orders |
| [Sync Logging API](https://docs.sparklayer.io/developers/api/sync-log.md) | Record when each data sync ran, and which records failed and why |

## Base URLs

| Environment | Base URL |
| --- | --- |
| Live | `https://app.sparklayer.io` |
| Test | `https://test.app.sparklayer.io` |

All the APIs share the same base URL. Live and test hold separate data and use separate API keys: see [Test mode](https://docs.sparklayer.io/help/dashboard/test-mode.md).

## Authentication

The APIs use the OAuth 2.0 client credentials flow:

1. Create an API key in the Dashboard, at **Settings > API** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/api)), or **SparkLayer Wholesale > Settings > API** in the Shopify app.
2. Exchange its client ID and secret for an access token at `POST /api/auth/token`. Tokens are valid for one hour.
3. Send the token as `Authorization: Bearer <ACCESS_TOKEN>`, with your Site ID in the `Site-Id` header, on every request.

See [Authentication](https://docs.sparklayer.io/developers/authentication.md) for the full flow, or the [quickstart](https://docs.sparklayer.io/developers/quickstart.md) to make your first call.

## Requests and responses

- Request and response bodies are JSON. Send `Content-Type: application/json` with any request that has a body.
- Send a `User-Agent` header that identifies your integration, so our support team can find your requests.
- Errors return an HTTP status code and a JSON body describing the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).
- Some list endpoints return results in pages: see [Pagination](https://docs.sparklayer.io/developers/pagination.md).

## Ignite

[Ignite](https://docs.sparklayer.io/ignite.md) connects SparkLayer to an eCommerce platform it doesn't have a ready-made integration for. It works the other way round from the APIs above: instead of your code calling SparkLayer, SparkLayer calls a service you build. That service answers [SparkLayer's requests](https://docs.sparklayer.io/ignite/api.md), for example to create customers, work out tax and shipping, complete checkout and sync data from your platform.

## Next steps

- [Quickstart](https://docs.sparklayer.io/developers/quickstart.md): make your first API request.
- [Authentication](https://docs.sparklayer.io/developers/authentication.md): handle tokens and token expiry.
- [Pricing API](https://docs.sparklayer.io/developers/api/pricing.md): the API most integrations start with.


---

# Core API

URL: https://docs.sparklayer.io/developers/api/core

Manage customer groups, discounts, shipping methods and settings with the Core API, delete customers and look up customer-specific pricing.

The Core API manages the configuration that controls how your B2B customers buy: customer groups, discounts, shipping methods and settings. It also lets you remove customers and check the prices a specific customer would pay.

## What the Core API covers

| Area | What you can do |
| --- | --- |
| Customer groups | List, create, update and delete customer groups, which can nest under a parent group |
| Discounts | List, create, update and delete discounts, and set the order in which they apply |
| Shipping | List, create, update and delete the shipping methods offered at checkout |
| Settings | Read and update global settings, such as price list selection, payment methods and order validation, and override them per customer group |
| Customers | Delete a customer, and fetch the prices a customer would pay for a list of SKUs |

## Where other data comes from

Products and customers aren't created through the Core API. SparkLayer syncs them from your eCommerce platform — through a built-in integration such as [Shopify](https://docs.sparklayer.io/help/platforms/shopify.md) or through [Ignite](https://docs.sparklayer.io/ignite.md) for other platforms.

For other B2B data, use the dedicated API:

| Data | API |
| --- | --- |
| Price lists and prices | [Pricing API](https://docs.sparklayer.io/developers/api/pricing.md) |
| Stock levels and stock locations | [Stock API](https://docs.sparklayer.io/developers/api/stock.md) |
| Orders, quotes and purchase transactions shown in My Account | [Purchasing API](https://docs.sparklayer.io/developers/api/purchasing.md) |
| Carts and orders placed on behalf of a customer | [Ordering API](https://docs.sparklayer.io/developers/api/ordering.md) |
| Files such as order attachments | [Files API](https://docs.sparklayer.io/developers/api/files.md) |
| Data sync status and errors | [Sync Logging API](https://docs.sparklayer.io/developers/api/sync-log.md) |

See the [API overview](https://docs.sparklayer.io/developers/api.md) for base URLs and authentication.

## Endpoints

- [DELETE Delete a customer](https://docs.sparklayer.io/developers/api/core/delete-a-customer.md)
- [POST Get customer-specific pricing](https://docs.sparklayer.io/developers/api/core/get-customer-specific-pricing.md)
- [GET List discounts](https://docs.sparklayer.io/developers/api/core/list-of-discounts.md)
- [POST Create a discount](https://docs.sparklayer.io/developers/api/core/create-a-discount.md)
- [PATCH Update discount priorities](https://docs.sparklayer.io/developers/api/core/update-discount-priorities.md)
- [GET Get a discount](https://docs.sparklayer.io/developers/api/core/get-a-discount.md)
- [PATCH Update a discount](https://docs.sparklayer.io/developers/api/core/update-a-discount.md)
- [DELETE Delete a discount](https://docs.sparklayer.io/developers/api/core/delete-a-discount.md)
- [GET List shipping methods](https://docs.sparklayer.io/developers/api/core/list-of-shipping-methods.md)
- [POST Create a shipping method](https://docs.sparklayer.io/developers/api/core/create-a-shipping-method.md)
- [GET Get a shipping method](https://docs.sparklayer.io/developers/api/core/get-a-shipping-method.md)
- [PATCH Update a shipping method](https://docs.sparklayer.io/developers/api/core/update-a-shipping-method.md)
- [DELETE Delete a shipping method](https://docs.sparklayer.io/developers/api/core/delete-a-shipping-method.md)
- [GET List global settings](https://docs.sparklayer.io/developers/api/core/list-global-settings.md)
- [PATCH Update global settings](https://docs.sparklayer.io/developers/api/core/update-global-setting.md)
- [GET List customer group settings](https://docs.sparklayer.io/developers/api/core/list-customer-group-settings.md)
- [PATCH Update customer group settings](https://docs.sparklayer.io/developers/api/core/update-customer-group-setting.md)
- [GET List customer groups](https://docs.sparklayer.io/developers/api/core/list-customer-groups.md)
- [POST Create a customer group](https://docs.sparklayer.io/developers/api/core/new-customer-group.md)
- [PATCH Update a customer group](https://docs.sparklayer.io/developers/api/core/update-customer-group.md)
- [DELETE Delete a customer group](https://docs.sparklayer.io/developers/api/core/delete-customer-group.md)
- [POST Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md)

## Next steps

- [Authentication](https://docs.sparklayer.io/developers/authentication.md): get an access token for your requests.
- [Pricing API](https://docs.sparklayer.io/developers/api/pricing.md): sync price lists and prices.


---

# Get an access token

URL: https://docs.sparklayer.io/developers/api/core/get-an-access-token
Operation: `POST /api/auth/token` (operationId `getAccessToken`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Exchanges an API key's Client ID and Client Secret for an access token (the OAuth 2.0 client credentials grant). Send the credentials as JSON with `Content-Type: application/json`: the endpoint doesn't accept a form-encoded body, so standard OAuth 2.0 client libraries won't work. Send the token as `Authorization: Bearer <access_token>`, with the same `Site-Id` header, on every other request.

Tokens are valid for 3,600 seconds (`expires_in`), and only for the Site ID and environment (live or test) they were issued for. There's no refresh token: cache the token and request a new one shortly before it expires. Create API keys in the SparkLayer Dashboard under **Settings > API**; deleting a key revokes its tokens. See [Authentication](https://docs.sparklayer.io/developers/authentication.md).

`POST /api/auth/token`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** none: this endpoint issues the access token. See [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/auth/token" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}'
```

Set `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `grant_type` | "client_credentials" | Yes | Always `client_credentials`. |
| `client_id` | string | Yes | The Client ID shown when you created the API key. |
| `client_secret` | string | Yes | The Client Secret shown when you created the API key. |

```json
{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}
```

### Responses

#### 200: The access token.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `token_type` | "Bearer" | Yes | Always `Bearer`. |
| `expires_in` | integer | Yes | Seconds until the token expires: tokens are valid for 1 hour. |
| `access_token` | string | Yes | The token to send in the `Authorization: Bearer <access_token>` header. It only works with the Site ID and environment it was issued for. |

```json
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ5b3VyLWNsaWVudC1pZCJ9.c2lnbmF0dXJl"
}
```

#### 400: The `Site-Id` header, a required field or `Content-Type: application/json` is missing (`invalid_request`), or `grant_type` isn't `client_credentials` (`unsupported_grant_type`).

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | "invalid_request" \| "unsupported_grant_type" \| "invalid_client" | Yes | `invalid_request`: a required field is missing. `unsupported_grant_type`: `grant_type` isn't `client_credentials`. `invalid_client`: the client ID or secret is wrong, the key has been deleted, or it belongs to the other environment. |
| `status` | integer | Yes | The HTTP status code. |
| `detail` | string | Yes | A human-readable explanation, for logging and debugging. |

```json
{
  "title": "unsupported_grant_type",
  "status": 400,
  "detail": "The authorization grant type is not supported"
}
```

#### 401: The client ID or secret is wrong, the key has been deleted, or it belongs to the other environment (`invalid_client`).

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | "invalid_request" \| "unsupported_grant_type" \| "invalid_client" | Yes | `invalid_request`: a required field is missing. `unsupported_grant_type`: `grant_type` isn't `client_credentials`. `invalid_client`: the client ID or secret is wrong, the key has been deleted, or it belongs to the other environment. |
| `status` | integer | Yes | The HTTP status code. |
| `detail` | string | Yes | A human-readable explanation, for logging and debugging. |

```json
{
  "title": "invalid_client",
  "status": 401,
  "detail": "Client authentication failed"
}
```


---

# Delete a customer

URL: https://docs.sparklayer.io/developers/api/core/delete-a-customer
Operation: `DELETE /api/v1/customers/{lookupBy}/{id}` (operationId `deleteCustomer`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Permanently deletes a customer and returns `204`. Set `lookupBy` to `sparklayer` (a `cu_`-prefixed ID or the customer's UUID), `platform` (the ID from your eCommerce platform) or `email` (URL-encoded). Returns `404` if no customer matches, or `400` (`resource-id-invalid`) if the ID isn't in the expected format.

`DELETE /api/v1/customers/{lookupBy}/{id}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X DELETE "https://app.sparklayer.io/api/v1/customers/sparklayer/cu_123" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `lookupBy` | "sparklayer" \| "platform" \| "email" | Yes | What `id` is: `sparklayer` (the customer's SparkLayer ID, `cu_`-prefixed or a UUID), `platform` (the ID from your eCommerce platform) or `email` (URL-encoded). Example: `sparklayer` |
| `id` | string | Yes | The customer identifier, of the kind set by `lookupBy`. Example: `cu_123` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 204: The customer was deleted. No body.

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Get customer-specific pricing

URL: https://docs.sparklayer.io/developers/api/core/get-customer-specific-pricing
Operation: `POST /api/v1/fetch-customer-pricing` (operationId `getCustomerPricing`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Returns the net unit price, line total and quantity price breaks a customer would get for each SKU, based on their price lists and any customer discount percentage. If some SKUs can't be priced the response is `207`, and those line items have an `error` message instead of prices. Returns `400` if the customer can't be found or has no price lists, or if `customer_lookup_by` is `sparklayer` and `customer_id` isn't a UUID.

`POST /api/v1/fetch-customer-pricing`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/fetch-customer-pricing" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "123e4567-e89b-12d3-a456-426614174000",
  "customer_lookup_by": "sparklayer",
  "line_items": [
    {
      "sku": "WIDGET-RED-M",
      "quantity": 10
    },
    {
      "sku": "WIDGET-BLUE-L",
      "quantity": 25
    }
  ]
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `customer_id` | string | Yes | The customer identifier, of the kind set by `customer_lookup_by`. |
| `customer_lookup_by` | "sparklayer" \| "platform" \| "email" | Yes | What `customer_id` is: `sparklayer` (the customer's SparkLayer ID, a UUID), `platform` (the ID from your eCommerce platform) or `email`. |
| `line_items` | object[] | Yes | Items: min 1. |
| `line_items[].sku` | string | Yes | SKU. Length: min 1, max 128. |
| `line_items[].quantity` | integer | Yes | Min 1. |

```json
{
  "customer_id": "123e4567-e89b-12d3-a456-426614174000",
  "customer_lookup_by": "sparklayer",
  "line_items": [
    {
      "sku": "WIDGET-RED-M",
      "quantity": 10
    },
    {
      "sku": "WIDGET-BLUE-L",
      "quantity": 25
    }
  ]
}
```

### Responses

#### 200: Successful response — all line items resolved pricing

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `line_items` | object[] | | |
| `line_items[].sku` | string | | |
| `line_items[].quantity` | integer | | |
| `line_items[].error` | string \| null | | Populated when pricing could not be determined for this SKU; null on success |
| `line_items[].currency_code` | string \| null | | |
| `line_items[].unit_price` | object \| null | | |
| `line_items[].unit_price.net` | string | | |
| `line_items[].line_total` | object \| null | | |
| `line_items[].line_total.net` | string | | |
| `line_items[].quantity_price_breaks` | object[] \| null | | |
| `line_items[].quantity_price_breaks[].min_quantity` | integer | | |
| `line_items[].quantity_price_breaks[].price` | object | | |
| `line_items[].quantity_price_breaks[].price.net` | string | | |
| `line_items[].quantity_price_breaks[].unit_of_measure` | string \| null | | |

```json
{
  "line_items": [
    {
      "sku": "WIDGET-RED-M",
      "quantity": 10,
      "error": null,
      "currency_code": "USD",
      "unit_price": {
        "net": "8.500000"
      },
      "line_total": {
        "net": "85.000000"
      },
      "quantity_price_breaks": [
        {
          "min_quantity": 1,
          "price": {
            "net": "10.000000"
          },
          "unit_of_measure": "box"
        },
        {
          "min_quantity": 10,
          "price": {
            "net": "8.500000"
          },
          "unit_of_measure": "box"
        }
      ]
    }
  ]
}
```

#### 207: Partial success — one or more line items could not be priced

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `line_items` | object[] | | |
| `line_items[].sku` | string | | |
| `line_items[].quantity` | integer | | |
| `line_items[].error` | string \| null | | Populated when pricing could not be determined for this SKU; null on success |
| `line_items[].currency_code` | string \| null | | |
| `line_items[].unit_price` | object \| null | | |
| `line_items[].unit_price.net` | string | | |
| `line_items[].line_total` | object \| null | | |
| `line_items[].line_total.net` | string | | |
| `line_items[].quantity_price_breaks` | object[] \| null | | |
| `line_items[].quantity_price_breaks[].min_quantity` | integer | | |
| `line_items[].quantity_price_breaks[].price` | object | | |
| `line_items[].quantity_price_breaks[].price.net` | string | | |
| `line_items[].quantity_price_breaks[].unit_of_measure` | string \| null | | |

```json
{
  "line_items": [
    {
      "sku": "WIDGET-RED-M",
      "quantity": 10,
      "error": null,
      "currency_code": "USD",
      "unit_price": {
        "net": "8.500000"
      },
      "line_total": {
        "net": "85.000000"
      },
      "quantity_price_breaks": [
        {
          "min_quantity": 1,
          "price": {
            "net": "10.000000"
          },
          "unit_of_measure": "box"
        }
      ]
    },
    {
      "sku": "WIDGET-BLUE-L",
      "quantity": 25,
      "error": "Pricing not found for SKU 'WIDGET-BLUE-L'",
      "currency_code": null,
      "unit_price": null,
      "line_total": null,
      "quantity_price_breaks": null
    }
  ]
}
```

#### 400: Validation error

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# List customer groups

URL: https://docs.sparklayer.io/developers/api/core/list-customer-groups
Operation: `GET /api/v1/customer-groups` (operationId `listCustomerGroups`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Returns every customer group with its `slug`, `name` and `parent_slug` as a single array. The list isn't paginated.

`GET /api/v1/customer-groups`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/customer-groups" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: Every customer group.

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].slug` | string | Yes | Length: max 128. |
| `[].name` | string | Yes | Length: max 256. |
| `[].parent_slug` | string | | Length: max 128. |

```json
[
  {
    "slug": "eu_gbp",
    "name": "Europe (GBP) Customers",
    "parent_slug": "base"
  }
]
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Create a customer group

URL: https://docs.sparklayer.io/developers/api/core/new-customer-group
Operation: `POST /api/v1/customer-groups` (operationId `createCustomerGroup`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Creates a customer group and returns the full, updated list of groups. `parent_slug` defaults to `base` and must be an existing group. A `slug` that's already in use returns `400` (`resource-already-exists`), and an unknown parent returns `400` (`resource-id-not-found`).

`POST /api/v1/customer-groups`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/customer-groups" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "slug": "eu_gbp",
  "name": "Europe (GBP) Customers",
  "parent_slug": "base"
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | A unique identifier for the group: lowercase letters, numbers, `-`, `~` and `_`, starting with a letter. It can't be `null` or `default`. Length: max 128. Pattern: `^(?!^null$)(?!^default$)[a-z]([a-z0-9\-~_]*$)`. |
| `name` | string | Yes | The group's display name. Length: max 256. |
| `parent_slug` | string | | The slug of an existing group to inherit from. Defaults to `base`. Length: max 128. |

```json
{
  "slug": "eu_gbp",
  "name": "Europe (GBP) Customers",
  "parent_slug": "base"
}
```

### Responses

#### 200: Every customer group, including the new one.

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].slug` | string | Yes | Length: max 128. |
| `[].name` | string | Yes | Length: max 256. |
| `[].parent_slug` | string | | Length: max 128. |

```json
[
  {
    "slug": "eu_gbp",
    "name": "Europe (GBP) Customers",
    "parent_slug": "base"
  }
]
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Delete a customer group

URL: https://docs.sparklayer.io/developers/api/core/delete-customer-group
Operation: `DELETE /api/v1/customer-groups/{slug}` (operationId `deleteCustomerGroup`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Deletes a customer group, along with any settings specific to it, and returns `204`. You can't delete a group that's still assigned to customers: this returns `400` (`resource-in-use`). An unknown slug returns `400` (`resource-id-not-found`).

`DELETE /api/v1/customer-groups/{slug}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X DELETE "https://app.sparklayer.io/api/v1/customer-groups/eu_gbp" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | The customer group's slug, as returned by **List customer groups** (for example `eu_gbp`). Example: `eu_gbp` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 204: The customer group was deleted. No body.

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Update a customer group

URL: https://docs.sparklayer.io/developers/api/core/update-customer-group
Operation: `PATCH /api/v1/customer-groups/{slug}` (operationId `updateCustomerGroup`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Sets the group's `name` and `parent_slug` and returns the full, updated list of groups. If you omit `parent_slug`, the parent is reset to `base`. An unknown slug returns `400` (`resource-id-not-found`) rather than `404`.

`PATCH /api/v1/customer-groups/{slug}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PATCH "https://app.sparklayer.io/api/v1/customer-groups/eu_gbp" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Europe (GBP) Customers",
  "parent_slug": "base"
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | The customer group's slug, as returned by **List customer groups** (for example `eu_gbp`). Example: `eu_gbp` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Length: max 256. |
| `parent_slug` | string | | Length: max 128. |

```json
{
  "name": "Europe (GBP) Customers",
  "parent_slug": "base"
}
```

### Responses

#### 200: Every customer group, including the updated one.

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].slug` | string | Yes | Length: max 128. |
| `[].name` | string | Yes | Length: max 256. |
| `[].parent_slug` | string | | Length: max 128. |

```json
[
  {
    "slug": "eu_gbp",
    "name": "Europe (GBP) Customers",
    "parent_slug": "base"
  }
]
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# List discounts

URL: https://docs.sparklayer.io/developers/api/core/list-of-discounts
Operation: `GET /api/v1/discounts` (operationId `listOfDiscounts`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Returns every discount that hasn't been deleted, both active and inactive, as a single array ordered by calculation group and then priority (highest first). The list isn't paginated.

`GET /api/v1/discounts`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/discounts" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: Every discount that hasn't been deleted, ordered by calculation group and then priority.

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].id` | string (uuid) | | Discount ID (uuid) |
| `[].created_at` | string (date-time) | | |
| `[].deleted_at` | string (date-time) \| null | | |
| `[].updated_at` | string (date-time) | | |
| `[].name` | string | | A user friendly name for the discount. Length: max 256. |
| `[].internal_name` | string | Yes | Length: max 45. |
| `[].internal_slug` | string | Yes | Length: max 45. |
| `[].template` | string \| null | | Discount template type. If not null allowed values are - 'order_level_get_amount_off', 'order_level_get_free_product', 'product_level_get_amount_off', 'order_level_get_shipping_reward', 'advanced_order_level_get_amount_off', 'order_level_requirement_amount_off', 'advanced_discount', 'advanced_free_products' |
| `[].calculation_group` | number | Yes | Dependency level = Calculation Group. All discounts with the same dependency level will share the same base, pre-discount totals. E.g. discount A (50% off) and discount B (50% off) will reward 100% off - not 75% off. Min 0, max 127. |
| `[].priority` | number | Yes | The sequence to apply the discounts (within each discount 'dependency level'). Min 0, max 10000. |
| `[].times_applicable_per_order` | number | Yes | Per order application limits. If -1 allow unlimited applications, otherwise limited. Min -1, max 127. |
| `[].max_rewards` | number \| null | | Used when rewardSelectionType is cheapest or expensive to determine the number of rewards available. Default: `1`. Min 1, max 127. |
| `[].groups` | string[] | Yes | Customer groups covered by this discount (use default to cover all groups) |
| `[].excluded_customers` | string[] | | Array of email address or accounting ids of customers to exclude from the discount |
| `[].simultaneity` | (string (uuid))[] \| null | | Other discounts which can be applied simultaneous, if null no limitation |
| `[].requirement_selection_type` | "any" \| "all" | Yes | Products which must be in the cart must match all or any one of the combo groups |
| `[].reward_selection_type` | "all" \| "cheapest" \| "expensive" | Yes | |
| `[].currency_code` | string \| null | Yes | Length: min 3, max 3. |
| `[].start_date` | string (date-time) \| null | Yes | Start Date |
| `[].end_date` | string (date-time) \| null | Yes | End Date |
| `[].active` | boolean | Yes | |
| `[].requirements` | object[] | Yes | |
| `[].requirements[].items` | object[] | Yes | |
| `[].requirements[].items[].restrictions` | object[] | Yes | |
| `[].requirements[].items[].restrictions[].type` | "productSKU" \| "excludeProductSKU" \| "productSKUContains" \| "excludeProductSKUContains" \| "productMetadata" \| "excludeProductMetadata" | Yes | |
| `[].requirements[].items[].restrictions[].ref` | string | Yes | |
| `[].requirements[].items[].restrictions[].metadata_namespace` | string \| null | | Length: max 256. |
| `[].requirements[].items[].restrictions[].metadata_key` | string \| null | | Length: max 128. |
| `[].requirements[].items[].points_type` | "line" \| "item" | Yes | Add X point(s) for each matching product OR Add X point(s) for once only |
| `[].requirements[].items[].points` | integer | Yes | Default: `1`. |
| `[].requirements[].items[].quantity` | integer | Yes | |
| `[].requirements[].items[].selection_type` | "minimum" \| "exact" | Yes | At least X quantity of product(s) must match OR Exactly X quantity of product(s) |
| `[].requirements[].max_rewards` | integer \| null | Yes | Limit the number of rewards when this requirement applies |
| `[].requirements[].min_spend` | number \| null | Yes | The cart must contain between min_spend and max_spend based on spend_tax_type of the requirement. |
| `[].requirements[].max_spend` | number \| null | Yes | |
| `[].requirements[].spend_tax_type` | "net" | Yes | |
| `[].requirements[].selection_type` | "minimum" \| "all" | Yes | Apply only if 'all' items matched in the cart OR if cart worth minimum of min_points requirement items(s) using requirements |
| `[].requirements[].min_points` | integer \| null | Yes | Only applies when selection_type is minimum |
| `[].rewards` | object[] | | |
| `[].rewards[].type` | "requirements\|all" \| "requirements\|cheapest" \| "cart\|productSKU" \| "cart\|cheapestProductSKU" \| "cart\|productMetadata" \| "cart\|cheapestProductMetadata" \| "product" \| "shipping" \| "order" | Yes | |
| `[].rewards[].amount_type` | "percent" \| "percentPreDiscount" \| "priceAllGross" \| "priceAllNet" \| "priceLineGross" \| "priceLineNet" \| "fixedAllGross" \| "fixedAllNet" \| "fixedLineGross" \| "fixedLineNet" \| "none" | Yes | |
| `[].rewards[].restriction_type` | "equals" \| "notEquals" \| "contains" \| "notContains" | | |
| `[].rewards[].item_id` | string | Yes | Length: max 100. |
| `[].rewards[].metadata_namespace` | string \| null | | Length: max 256. |
| `[].rewards[].metadata_key` | string \| null | | Length: max 128. |
| `[].rewards[].amount` | number | Yes | Max 1000000000. |
| `[].other_requirements` | (Discount.OtherRequirements.Coupons \| Discount.OtherRequirements.NumItems \| Discount.OtherRequirements.SpendAmount \| Discount.OtherRequirements.MaxUsesPerCustomer)[] | Yes | |
| `[].other_requirements[].requirement_type` | "coupons" | | |
| `[].other_requirements[].coupons` | object[] | | Items: min 1. |
| `[].other_requirements[].coupons[].code` | string | | |
| `[].other_requirements[].min` | number \| null | | |
| `[].other_requirements[].max` | number \| null | | |
| `[].other_requirements[].type` | "productsTotalItems" \| "productsTotalQuantity" | | |
| `[].other_requirements[].tax_type` | "net" | | |
| `[].other_requirements[].number` | number | | |

```json
[
  {
    "id": "942651af-f950-4716-9916-16170fe0645f",
    "created_at": "2026-01-31T09:00:00Z",
    "deleted_at": "2026-01-31T09:00:00Z",
    "updated_at": "2026-01-31T09:00:00Z",
    "name": "<name>",
    "internal_name": "<internal_name>",
    "internal_slug": "<internal_slug>",
    "template": "<template>",
    "calculation_group": 0,
    "priority": 0,
    "times_applicable_per_order": -1,
    "max_rewards": 1,
    "groups": [
      "default"
    ],
    "excluded_customers": [
      "customer@b2b.com"
    ],
    "simultaneity": [
      "default"
    ],
    "requirement_selection_type": "any",
    "reward_selection_type": "all",
    "currency_code": "gbp",
    "start_date": "2026-01-31T09:00:00Z",
    "end_date": "2026-01-31T09:00:00Z",
    "active": true,
    "requirements": [
      {
        "items": [
          {
            "restrictions": [
              {
                "type": "productSKU",
                "ref": "<ref>",
                "metadata_namespace": "erp",
                "metadata_key": "vendor"
              }
            ],
            "points_type": "line",
            "points": 1,
            "quantity": 0,
            "selection_type": "minimum"
          }
        ],
        "max_rewards": 0,
        "min_spend": 0,
        "max_spend": 0,
        "spend_tax_type": "net",
        "selection_type": "minimum",
        "min_points": 0
      }
    ],
    "rewards": [
      {
        "type": "requirements|all",
        "amount_type": "percent",
        "restriction_type": "equals",
        "item_id": "<item_id>",
        "metadata_namespace": "erp",
        "metadata_key": "vendor",
        "amount": 0
      }
    ],
    "other_requirements": [
      {
        "requirement_type": "coupons",
        "coupons": [
          {
            "code": "<code>"
          }
        ]
      }
    ]
  }
]
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Create a discount

URL: https://docs.sparklayer.io/developers/api/core/create-a-discount
Operation: `POST /api/v1/discounts` (operationId `createDiscount`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Creates a discount and returns it with its generated UUID. `currency_code` is required when a reward or other requirement is based on a monetary amount, and coupon codes may only contain letters, numbers, underscores and hyphens. A discount can have at most 10 requirements (with up to 10 items each) and 25 rewards; breaking any of these rules returns `400`.

`POST /api/v1/discounts`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/discounts" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "<name>",
  "internal_name": "<internal_name>",
  "internal_slug": "<internal_slug>",
  "template": "<template>",
  "calculation_group": 0,
  "priority": 0,
  "times_applicable_per_order": -1,
  "max_rewards": 1,
  "groups": [
    "default"
  ],
  "excluded_customers": [
    "customer@b2b.com"
  ],
  "simultaneity": [
    "default"
  ],
  "requirement_selection_type": "any",
  "reward_selection_type": "all",
  "currency_code": "gbp",
  "start_date": "2026-01-31T09:00:00Z",
  "end_date": "2026-01-31T09:00:00Z",
  "active": true,
  "requirements": [
    {
      "items": [
        {
          "restrictions": [
            {
              "type": "productSKU",
              "ref": "<ref>",
              "metadata_namespace": "erp",
              "metadata_key": "vendor"
            }
          ],
          "points_type": "line",
          "points": 1,
          "quantity": 0,
          "selection_type": "minimum"
        }
      ],
      "max_rewards": 0,
      "min_spend": 0,
      "max_spend": 0,
      "spend_tax_type": "net",
      "selection_type": "minimum",
      "min_points": 0
    }
  ],
  "rewards": [
    {
      "type": "requirements|all",
      "amount_type": "percent",
      "restriction_type": "equals",
      "item_id": "<item_id>",
      "metadata_namespace": "erp",
      "metadata_key": "vendor",
      "amount": 0
    }
  ],
  "other_requirements": [
    {
      "requirement_type": "coupons",
      "coupons": [
        {
          "code": "<code>"
        }
      ]
    }
  ]
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | | A user friendly name for the discount. Length: max 256. |
| `internal_name` | string | Yes | Length: max 45. |
| `internal_slug` | string | Yes | Length: max 45. |
| `template` | string \| null | | Discount template type. If not null allowed values are - 'order_level_get_amount_off', 'order_level_get_free_product', 'product_level_get_amount_off', 'order_level_get_shipping_reward', 'advanced_order_level_get_amount_off', 'order_level_requirement_amount_off', 'advanced_discount', 'advanced_free_products' |
| `calculation_group` | number | Yes | Dependency level = Calculation Group. All discounts with the same dependency level will share the same base, pre-discount totals. E.g. discount A (50% off) and discount B (50% off) will reward 100% off - not 75% off. Min 0, max 127. |
| `priority` | number | Yes | The sequence to apply the discounts (within each discount 'dependency level'). Min 0, max 10000. |
| `times_applicable_per_order` | number | Yes | Per order application limits. If -1 allow unlimited applications, otherwise limited. Min -1, max 127. |
| `max_rewards` | number \| null | | Used when rewardSelectionType is cheapest or expensive to determine the number of rewards available. Default: `1`. Min 1, max 127. |
| `groups` | string[] | Yes | Customer groups covered by this discount (use default to cover all groups) |
| `excluded_customers` | string[] | | Array of email address or accounting ids of customers to exclude from the discount |
| `simultaneity` | (string (uuid))[] \| null | | Other discounts which can be applied simultaneous, if null no limitation |
| `requirement_selection_type` | "any" \| "all" | Yes | Products which must be in the cart must match all or any one of the combo groups |
| `reward_selection_type` | "all" \| "cheapest" \| "expensive" | Yes | |
| `currency_code` | string \| null | Yes | Length: min 3, max 3. |
| `start_date` | string (date-time) \| null | Yes | Start Date |
| `end_date` | string (date-time) \| null | Yes | End Date |
| `active` | boolean | Yes | |
| `requirements` | object[] | Yes | |
| `requirements[].items` | object[] | Yes | |
| `requirements[].items[].restrictions` | object[] | Yes | |
| `requirements[].items[].restrictions[].type` | "productSKU" \| "excludeProductSKU" \| "productSKUContains" \| "excludeProductSKUContains" \| "productMetadata" \| "excludeProductMetadata" | Yes | |
| `requirements[].items[].restrictions[].ref` | string | Yes | |
| `requirements[].items[].restrictions[].metadata_namespace` | string \| null | | Length: max 256. |
| `requirements[].items[].restrictions[].metadata_key` | string \| null | | Length: max 128. |
| `requirements[].items[].points_type` | "line" \| "item" | Yes | Add X point(s) for each matching product OR Add X point(s) for once only |
| `requirements[].items[].points` | integer | Yes | Default: `1`. |
| `requirements[].items[].quantity` | integer | Yes | |
| `requirements[].items[].selection_type` | "minimum" \| "exact" | Yes | At least X quantity of product(s) must match OR Exactly X quantity of product(s) |
| `requirements[].max_rewards` | integer \| null | Yes | Limit the number of rewards when this requirement applies |
| `requirements[].min_spend` | number \| null | Yes | The cart must contain between min_spend and max_spend based on spend_tax_type of the requirement. |
| `requirements[].max_spend` | number \| null | Yes | |
| `requirements[].spend_tax_type` | "net" | Yes | |
| `requirements[].selection_type` | "minimum" \| "all" | Yes | Apply only if 'all' items matched in the cart OR if cart worth minimum of min_points requirement items(s) using requirements |
| `requirements[].min_points` | integer \| null | Yes | Only applies when selection_type is minimum |
| `rewards` | object[] | | |
| `rewards[].type` | "requirements\|all" \| "requirements\|cheapest" \| "cart\|productSKU" \| "cart\|cheapestProductSKU" \| "cart\|productMetadata" \| "cart\|cheapestProductMetadata" \| "product" \| "shipping" \| "order" | Yes | |
| `rewards[].amount_type` | "percent" \| "percentPreDiscount" \| "priceAllGross" \| "priceAllNet" \| "priceLineGross" \| "priceLineNet" \| "fixedAllGross" \| "fixedAllNet" \| "fixedLineGross" \| "fixedLineNet" \| "none" | Yes | |
| `rewards[].restriction_type` | "equals" \| "notEquals" \| "contains" \| "notContains" | | |
| `rewards[].item_id` | string | Yes | Length: max 100. |
| `rewards[].metadata_namespace` | string \| null | | Length: max 256. |
| `rewards[].metadata_key` | string \| null | | Length: max 128. |
| `rewards[].amount` | number | Yes | Max 1000000000. |
| `other_requirements` | (Discount.OtherRequirements.Coupons \| Discount.OtherRequirements.NumItems \| Discount.OtherRequirements.SpendAmount \| Discount.OtherRequirements.MaxUsesPerCustomer)[] | Yes | |
| `other_requirements[].requirement_type` | "coupons" | | |
| `other_requirements[].coupons` | object[] | | Items: min 1. |
| `other_requirements[].coupons[].code` | string | | |
| `other_requirements[].min` | number \| null | | |
| `other_requirements[].max` | number \| null | | |
| `other_requirements[].type` | "productsTotalItems" \| "productsTotalQuantity" | | |
| `other_requirements[].tax_type` | "net" | | |
| `other_requirements[].number` | number | | |

```json
{
  "name": "<name>",
  "internal_name": "<internal_name>",
  "internal_slug": "<internal_slug>",
  "template": "<template>",
  "calculation_group": 0,
  "priority": 0,
  "times_applicable_per_order": -1,
  "max_rewards": 1,
  "groups": [
    "default"
  ],
  "excluded_customers": [
    "customer@b2b.com"
  ],
  "simultaneity": [
    "default"
  ],
  "requirement_selection_type": "any",
  "reward_selection_type": "all",
  "currency_code": "gbp",
  "start_date": "2026-01-31T09:00:00Z",
  "end_date": "2026-01-31T09:00:00Z",
  "active": true,
  "requirements": [
    {
      "items": [
        {
          "restrictions": [
            {
              "type": "productSKU",
              "ref": "<ref>",
              "metadata_namespace": "erp",
              "metadata_key": "vendor"
            }
          ],
          "points_type": "line",
          "points": 1,
          "quantity": 0,
          "selection_type": "minimum"
        }
      ],
      "max_rewards": 0,
      "min_spend": 0,
      "max_spend": 0,
      "spend_tax_type": "net",
      "selection_type": "minimum",
      "min_points": 0
    }
  ],
  "rewards": [
    {
      "type": "requirements|all",
      "amount_type": "percent",
      "restriction_type": "equals",
      "item_id": "<item_id>",
      "metadata_namespace": "erp",
      "metadata_key": "vendor",
      "amount": 0
    }
  ],
  "other_requirements": [
    {
      "requirement_type": "coupons",
      "coupons": [
        {
          "code": "<code>"
        }
      ]
    }
  ]
}
```

### Responses

#### 200: The new discount, including its generated `id`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | | Discount ID (uuid) |
| `created_at` | string (date-time) | | |
| `deleted_at` | string (date-time) \| null | | |
| `updated_at` | string (date-time) | | |
| `name` | string | | A user friendly name for the discount. Length: max 256. |
| `internal_name` | string | Yes | Length: max 45. |
| `internal_slug` | string | Yes | Length: max 45. |
| `template` | string \| null | | Discount template type. If not null allowed values are - 'order_level_get_amount_off', 'order_level_get_free_product', 'product_level_get_amount_off', 'order_level_get_shipping_reward', 'advanced_order_level_get_amount_off', 'order_level_requirement_amount_off', 'advanced_discount', 'advanced_free_products' |
| `calculation_group` | number | Yes | Dependency level = Calculation Group. All discounts with the same dependency level will share the same base, pre-discount totals. E.g. discount A (50% off) and discount B (50% off) will reward 100% off - not 75% off. Min 0, max 127. |
| `priority` | number | Yes | The sequence to apply the discounts (within each discount 'dependency level'). Min 0, max 10000. |
| `times_applicable_per_order` | number | Yes | Per order application limits. If -1 allow unlimited applications, otherwise limited. Min -1, max 127. |
| `max_rewards` | number \| null | | Used when rewardSelectionType is cheapest or expensive to determine the number of rewards available. Default: `1`. Min 1, max 127. |
| `groups` | string[] | Yes | Customer groups covered by this discount (use default to cover all groups) |
| `excluded_customers` | string[] | | Array of email address or accounting ids of customers to exclude from the discount |
| `simultaneity` | (string (uuid))[] \| null | | Other discounts which can be applied simultaneous, if null no limitation |
| `requirement_selection_type` | "any" \| "all" | Yes | Products which must be in the cart must match all or any one of the combo groups |
| `reward_selection_type` | "all" \| "cheapest" \| "expensive" | Yes | |
| `currency_code` | string \| null | Yes | Length: min 3, max 3. |
| `start_date` | string (date-time) \| null | Yes | Start Date |
| `end_date` | string (date-time) \| null | Yes | End Date |
| `active` | boolean | Yes | |
| `requirements` | object[] | Yes | |
| `requirements[].items` | object[] | Yes | |
| `requirements[].items[].restrictions` | object[] | Yes | |
| `requirements[].items[].restrictions[].type` | "productSKU" \| "excludeProductSKU" \| "productSKUContains" \| "excludeProductSKUContains" \| "productMetadata" \| "excludeProductMetadata" | Yes | |
| `requirements[].items[].restrictions[].ref` | string | Yes | |
| `requirements[].items[].restrictions[].metadata_namespace` | string \| null | | Length: max 256. |
| `requirements[].items[].restrictions[].metadata_key` | string \| null | | Length: max 128. |
| `requirements[].items[].points_type` | "line" \| "item" | Yes | Add X point(s) for each matching product OR Add X point(s) for once only |
| `requirements[].items[].points` | integer | Yes | Default: `1`. |
| `requirements[].items[].quantity` | integer | Yes | |
| `requirements[].items[].selection_type` | "minimum" \| "exact" | Yes | At least X quantity of product(s) must match OR Exactly X quantity of product(s) |
| `requirements[].max_rewards` | integer \| null | Yes | Limit the number of rewards when this requirement applies |
| `requirements[].min_spend` | number \| null | Yes | The cart must contain between min_spend and max_spend based on spend_tax_type of the requirement. |
| `requirements[].max_spend` | number \| null | Yes | |
| `requirements[].spend_tax_type` | "net" | Yes | |
| `requirements[].selection_type` | "minimum" \| "all" | Yes | Apply only if 'all' items matched in the cart OR if cart worth minimum of min_points requirement items(s) using requirements |
| `requirements[].min_points` | integer \| null | Yes | Only applies when selection_type is minimum |
| `rewards` | object[] | | |
| `rewards[].type` | "requirements\|all" \| "requirements\|cheapest" \| "cart\|productSKU" \| "cart\|cheapestProductSKU" \| "cart\|productMetadata" \| "cart\|cheapestProductMetadata" \| "product" \| "shipping" \| "order" | Yes | |
| `rewards[].amount_type` | "percent" \| "percentPreDiscount" \| "priceAllGross" \| "priceAllNet" \| "priceLineGross" \| "priceLineNet" \| "fixedAllGross" \| "fixedAllNet" \| "fixedLineGross" \| "fixedLineNet" \| "none" | Yes | |
| `rewards[].restriction_type` | "equals" \| "notEquals" \| "contains" \| "notContains" | | |
| `rewards[].item_id` | string | Yes | Length: max 100. |
| `rewards[].metadata_namespace` | string \| null | | Length: max 256. |
| `rewards[].metadata_key` | string \| null | | Length: max 128. |
| `rewards[].amount` | number | Yes | Max 1000000000. |
| `other_requirements` | (Discount.OtherRequirements.Coupons \| Discount.OtherRequirements.NumItems \| Discount.OtherRequirements.SpendAmount \| Discount.OtherRequirements.MaxUsesPerCustomer)[] | Yes | |
| `other_requirements[].requirement_type` | "coupons" | | |
| `other_requirements[].coupons` | object[] | | Items: min 1. |
| `other_requirements[].coupons[].code` | string | | |
| `other_requirements[].min` | number \| null | | |
| `other_requirements[].max` | number \| null | | |
| `other_requirements[].type` | "productsTotalItems" \| "productsTotalQuantity" | | |
| `other_requirements[].tax_type` | "net" | | |
| `other_requirements[].number` | number | | |

```json
{
  "id": "942651af-f950-4716-9916-16170fe0645f",
  "created_at": "2026-01-31T09:00:00Z",
  "deleted_at": "2026-01-31T09:00:00Z",
  "updated_at": "2026-01-31T09:00:00Z",
  "name": "<name>",
  "internal_name": "<internal_name>",
  "internal_slug": "<internal_slug>",
  "template": "<template>",
  "calculation_group": 0,
  "priority": 0,
  "times_applicable_per_order": -1,
  "max_rewards": 1,
  "groups": [
    "default"
  ],
  "excluded_customers": [
    "customer@b2b.com"
  ],
  "simultaneity": [
    "default"
  ],
  "requirement_selection_type": "any",
  "reward_selection_type": "all",
  "currency_code": "gbp",
  "start_date": "2026-01-31T09:00:00Z",
  "end_date": "2026-01-31T09:00:00Z",
  "active": true,
  "requirements": [
    {
      "items": [
        {
          "restrictions": [
            {
              "type": "productSKU",
              "ref": "<ref>",
              "metadata_namespace": "erp",
              "metadata_key": "vendor"
            }
          ],
          "points_type": "line",
          "points": 1,
          "quantity": 0,
          "selection_type": "minimum"
        }
      ],
      "max_rewards": 0,
      "min_spend": 0,
      "max_spend": 0,
      "spend_tax_type": "net",
      "selection_type": "minimum",
      "min_points": 0
    }
  ],
  "rewards": [
    {
      "type": "requirements|all",
      "amount_type": "percent",
      "restriction_type": "equals",
      "item_id": "<item_id>",
      "metadata_namespace": "erp",
      "metadata_key": "vendor",
      "amount": 0
    }
  ],
  "other_requirements": [
    {
      "requirement_type": "coupons",
      "coupons": [
        {
          "code": "<code>"
        }
      ]
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Update discount priorities

URL: https://docs.sparklayer.io/developers/api/core/update-discount-priorities
Operation: `PATCH /api/v1/set-discount-priorities` (operationId `updateDiscountPriorities`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Sets the `priority` of several discounts in a single transaction and returns the full list of discounts. Every `id` and every `priority` in the request must be unique, otherwise you get a `400`. IDs that don't match a discount are ignored.

`PATCH /api/v1/set-discount-priorities`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PATCH "https://app.sparklayer.io/api/v1/set-discount-priorities" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "id": "942651af-f950-4716-9916-16170fe0645f",
    "priority": 0
  }
]'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].id` | string (uuid) | Yes | Discount ID (uuid) |
| `[].priority` | integer | Yes | Discount priority |

```json
[
  {
    "id": "942651af-f950-4716-9916-16170fe0645f",
    "priority": 0
  }
]
```

### Responses

#### 200: Every discount, with the updated priorities.

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].id` | string (uuid) | | Discount ID (uuid) |
| `[].created_at` | string (date-time) | | |
| `[].deleted_at` | string (date-time) \| null | | |
| `[].updated_at` | string (date-time) | | |
| `[].name` | string | | A user friendly name for the discount. Length: max 256. |
| `[].internal_name` | string | Yes | Length: max 45. |
| `[].internal_slug` | string | Yes | Length: max 45. |
| `[].template` | string \| null | | Discount template type. If not null allowed values are - 'order_level_get_amount_off', 'order_level_get_free_product', 'product_level_get_amount_off', 'order_level_get_shipping_reward', 'advanced_order_level_get_amount_off', 'order_level_requirement_amount_off', 'advanced_discount', 'advanced_free_products' |
| `[].calculation_group` | number | Yes | Dependency level = Calculation Group. All discounts with the same dependency level will share the same base, pre-discount totals. E.g. discount A (50% off) and discount B (50% off) will reward 100% off - not 75% off. Min 0, max 127. |
| `[].priority` | number | Yes | The sequence to apply the discounts (within each discount 'dependency level'). Min 0, max 10000. |
| `[].times_applicable_per_order` | number | Yes | Per order application limits. If -1 allow unlimited applications, otherwise limited. Min -1, max 127. |
| `[].max_rewards` | number \| null | | Used when rewardSelectionType is cheapest or expensive to determine the number of rewards available. Default: `1`. Min 1, max 127. |
| `[].groups` | string[] | Yes | Customer groups covered by this discount (use default to cover all groups) |
| `[].excluded_customers` | string[] | | Array of email address or accounting ids of customers to exclude from the discount |
| `[].simultaneity` | (string (uuid))[] \| null | | Other discounts which can be applied simultaneous, if null no limitation |
| `[].requirement_selection_type` | "any" \| "all" | Yes | Products which must be in the cart must match all or any one of the combo groups |
| `[].reward_selection_type` | "all" \| "cheapest" \| "expensive" | Yes | |
| `[].currency_code` | string \| null | Yes | Length: min 3, max 3. |
| `[].start_date` | string (date-time) \| null | Yes | Start Date |
| `[].end_date` | string (date-time) \| null | Yes | End Date |
| `[].active` | boolean | Yes | |
| `[].requirements` | object[] | Yes | |
| `[].requirements[].items` | object[] | Yes | |
| `[].requirements[].items[].restrictions` | object[] | Yes | |
| `[].requirements[].items[].restrictions[].type` | "productSKU" \| "excludeProductSKU" \| "productSKUContains" \| "excludeProductSKUContains" \| "productMetadata" \| "excludeProductMetadata" | Yes | |
| `[].requirements[].items[].restrictions[].ref` | string | Yes | |
| `[].requirements[].items[].restrictions[].metadata_namespace` | string \| null | | Length: max 256. |
| `[].requirements[].items[].restrictions[].metadata_key` | string \| null | | Length: max 128. |
| `[].requirements[].items[].points_type` | "line" \| "item" | Yes | Add X point(s) for each matching product OR Add X point(s) for once only |
| `[].requirements[].items[].points` | integer | Yes | Default: `1`. |
| `[].requirements[].items[].quantity` | integer | Yes | |
| `[].requirements[].items[].selection_type` | "minimum" \| "exact" | Yes | At least X quantity of product(s) must match OR Exactly X quantity of product(s) |
| `[].requirements[].max_rewards` | integer \| null | Yes | Limit the number of rewards when this requirement applies |
| `[].requirements[].min_spend` | number \| null | Yes | The cart must contain between min_spend and max_spend based on spend_tax_type of the requirement. |
| `[].requirements[].max_spend` | number \| null | Yes | |
| `[].requirements[].spend_tax_type` | "net" | Yes | |
| `[].requirements[].selection_type` | "minimum" \| "all" | Yes | Apply only if 'all' items matched in the cart OR if cart worth minimum of min_points requirement items(s) using requirements |
| `[].requirements[].min_points` | integer \| null | Yes | Only applies when selection_type is minimum |
| `[].rewards` | object[] | | |
| `[].rewards[].type` | "requirements\|all" \| "requirements\|cheapest" \| "cart\|productSKU" \| "cart\|cheapestProductSKU" \| "cart\|productMetadata" \| "cart\|cheapestProductMetadata" \| "product" \| "shipping" \| "order" | Yes | |
| `[].rewards[].amount_type` | "percent" \| "percentPreDiscount" \| "priceAllGross" \| "priceAllNet" \| "priceLineGross" \| "priceLineNet" \| "fixedAllGross" \| "fixedAllNet" \| "fixedLineGross" \| "fixedLineNet" \| "none" | Yes | |
| `[].rewards[].restriction_type` | "equals" \| "notEquals" \| "contains" \| "notContains" | | |
| `[].rewards[].item_id` | string | Yes | Length: max 100. |
| `[].rewards[].metadata_namespace` | string \| null | | Length: max 256. |
| `[].rewards[].metadata_key` | string \| null | | Length: max 128. |
| `[].rewards[].amount` | number | Yes | Max 1000000000. |
| `[].other_requirements` | (Discount.OtherRequirements.Coupons \| Discount.OtherRequirements.NumItems \| Discount.OtherRequirements.SpendAmount \| Discount.OtherRequirements.MaxUsesPerCustomer)[] | Yes | |
| `[].other_requirements[].requirement_type` | "coupons" | | |
| `[].other_requirements[].coupons` | object[] | | Items: min 1. |
| `[].other_requirements[].coupons[].code` | string | | |
| `[].other_requirements[].min` | number \| null | | |
| `[].other_requirements[].max` | number \| null | | |
| `[].other_requirements[].type` | "productsTotalItems" \| "productsTotalQuantity" | | |
| `[].other_requirements[].tax_type` | "net" | | |
| `[].other_requirements[].number` | number | | |

```json
[
  {
    "id": "942651af-f950-4716-9916-16170fe0645f",
    "created_at": "2026-01-31T09:00:00Z",
    "deleted_at": "2026-01-31T09:00:00Z",
    "updated_at": "2026-01-31T09:00:00Z",
    "name": "<name>",
    "internal_name": "<internal_name>",
    "internal_slug": "<internal_slug>",
    "template": "<template>",
    "calculation_group": 0,
    "priority": 0,
    "times_applicable_per_order": -1,
    "max_rewards": 1,
    "groups": [
      "default"
    ],
    "excluded_customers": [
      "customer@b2b.com"
    ],
    "simultaneity": [
      "default"
    ],
    "requirement_selection_type": "any",
    "reward_selection_type": "all",
    "currency_code": "gbp",
    "start_date": "2026-01-31T09:00:00Z",
    "end_date": "2026-01-31T09:00:00Z",
    "active": true,
    "requirements": [
      {
        "items": [
          {
            "restrictions": [
              {
                "type": "productSKU",
                "ref": "<ref>",
                "metadata_namespace": "erp",
                "metadata_key": "vendor"
              }
            ],
            "points_type": "line",
            "points": 1,
            "quantity": 0,
            "selection_type": "minimum"
          }
        ],
        "max_rewards": 0,
        "min_spend": 0,
        "max_spend": 0,
        "spend_tax_type": "net",
        "selection_type": "minimum",
        "min_points": 0
      }
    ],
    "rewards": [
      {
        "type": "requirements|all",
        "amount_type": "percent",
        "restriction_type": "equals",
        "item_id": "<item_id>",
        "metadata_namespace": "erp",
        "metadata_key": "vendor",
        "amount": 0
      }
    ],
    "other_requirements": [
      {
        "requirement_type": "coupons",
        "coupons": [
          {
            "code": "<code>"
          }
        ]
      }
    ]
  }
]
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Get a discount

URL: https://docs.sparklayer.io/developers/api/core/get-a-discount
Operation: `GET /api/v1/discounts/{id}` (operationId `getDiscount`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Returns a single discount by its UUID. Returns `404` if the discount doesn't exist or has been deleted.

`GET /api/v1/discounts/{id}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/discounts/942651af-f950-4716-9916-16170fe0645f" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The discount's ID (a UUID). Example: `942651af-f950-4716-9916-16170fe0645f` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: The discount.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | | Discount ID (uuid) |
| `created_at` | string (date-time) | | |
| `deleted_at` | string (date-time) \| null | | |
| `updated_at` | string (date-time) | | |
| `name` | string | | A user friendly name for the discount. Length: max 256. |
| `internal_name` | string | Yes | Length: max 45. |
| `internal_slug` | string | Yes | Length: max 45. |
| `template` | string \| null | | Discount template type. If not null allowed values are - 'order_level_get_amount_off', 'order_level_get_free_product', 'product_level_get_amount_off', 'order_level_get_shipping_reward', 'advanced_order_level_get_amount_off', 'order_level_requirement_amount_off', 'advanced_discount', 'advanced_free_products' |
| `calculation_group` | number | Yes | Dependency level = Calculation Group. All discounts with the same dependency level will share the same base, pre-discount totals. E.g. discount A (50% off) and discount B (50% off) will reward 100% off - not 75% off. Min 0, max 127. |
| `priority` | number | Yes | The sequence to apply the discounts (within each discount 'dependency level'). Min 0, max 10000. |
| `times_applicable_per_order` | number | Yes | Per order application limits. If -1 allow unlimited applications, otherwise limited. Min -1, max 127. |
| `max_rewards` | number \| null | | Used when rewardSelectionType is cheapest or expensive to determine the number of rewards available. Default: `1`. Min 1, max 127. |
| `groups` | string[] | Yes | Customer groups covered by this discount (use default to cover all groups) |
| `excluded_customers` | string[] | | Array of email address or accounting ids of customers to exclude from the discount |
| `simultaneity` | (string (uuid))[] \| null | | Other discounts which can be applied simultaneous, if null no limitation |
| `requirement_selection_type` | "any" \| "all" | Yes | Products which must be in the cart must match all or any one of the combo groups |
| `reward_selection_type` | "all" \| "cheapest" \| "expensive" | Yes | |
| `currency_code` | string \| null | Yes | Length: min 3, max 3. |
| `start_date` | string (date-time) \| null | Yes | Start Date |
| `end_date` | string (date-time) \| null | Yes | End Date |
| `active` | boolean | Yes | |
| `requirements` | object[] | Yes | |
| `requirements[].items` | object[] | Yes | |
| `requirements[].items[].restrictions` | object[] | Yes | |
| `requirements[].items[].restrictions[].type` | "productSKU" \| "excludeProductSKU" \| "productSKUContains" \| "excludeProductSKUContains" \| "productMetadata" \| "excludeProductMetadata" | Yes | |
| `requirements[].items[].restrictions[].ref` | string | Yes | |
| `requirements[].items[].restrictions[].metadata_namespace` | string \| null | | Length: max 256. |
| `requirements[].items[].restrictions[].metadata_key` | string \| null | | Length: max 128. |
| `requirements[].items[].points_type` | "line" \| "item" | Yes | Add X point(s) for each matching product OR Add X point(s) for once only |
| `requirements[].items[].points` | integer | Yes | Default: `1`. |
| `requirements[].items[].quantity` | integer | Yes | |
| `requirements[].items[].selection_type` | "minimum" \| "exact" | Yes | At least X quantity of product(s) must match OR Exactly X quantity of product(s) |
| `requirements[].max_rewards` | integer \| null | Yes | Limit the number of rewards when this requirement applies |
| `requirements[].min_spend` | number \| null | Yes | The cart must contain between min_spend and max_spend based on spend_tax_type of the requirement. |
| `requirements[].max_spend` | number \| null | Yes | |
| `requirements[].spend_tax_type` | "net" | Yes | |
| `requirements[].selection_type` | "minimum" \| "all" | Yes | Apply only if 'all' items matched in the cart OR if cart worth minimum of min_points requirement items(s) using requirements |
| `requirements[].min_points` | integer \| null | Yes | Only applies when selection_type is minimum |
| `rewards` | object[] | | |
| `rewards[].type` | "requirements\|all" \| "requirements\|cheapest" \| "cart\|productSKU" \| "cart\|cheapestProductSKU" \| "cart\|productMetadata" \| "cart\|cheapestProductMetadata" \| "product" \| "shipping" \| "order" | Yes | |
| `rewards[].amount_type` | "percent" \| "percentPreDiscount" \| "priceAllGross" \| "priceAllNet" \| "priceLineGross" \| "priceLineNet" \| "fixedAllGross" \| "fixedAllNet" \| "fixedLineGross" \| "fixedLineNet" \| "none" | Yes | |
| `rewards[].restriction_type` | "equals" \| "notEquals" \| "contains" \| "notContains" | | |
| `rewards[].item_id` | string | Yes | Length: max 100. |
| `rewards[].metadata_namespace` | string \| null | | Length: max 256. |
| `rewards[].metadata_key` | string \| null | | Length: max 128. |
| `rewards[].amount` | number | Yes | Max 1000000000. |
| `other_requirements` | (Discount.OtherRequirements.Coupons \| Discount.OtherRequirements.NumItems \| Discount.OtherRequirements.SpendAmount \| Discount.OtherRequirements.MaxUsesPerCustomer)[] | Yes | |
| `other_requirements[].requirement_type` | "coupons" | | |
| `other_requirements[].coupons` | object[] | | Items: min 1. |
| `other_requirements[].coupons[].code` | string | | |
| `other_requirements[].min` | number \| null | | |
| `other_requirements[].max` | number \| null | | |
| `other_requirements[].type` | "productsTotalItems" \| "productsTotalQuantity" | | |
| `other_requirements[].tax_type` | "net" | | |
| `other_requirements[].number` | number | | |

```json
{
  "id": "942651af-f950-4716-9916-16170fe0645f",
  "created_at": "2026-01-31T09:00:00Z",
  "deleted_at": "2026-01-31T09:00:00Z",
  "updated_at": "2026-01-31T09:00:00Z",
  "name": "<name>",
  "internal_name": "<internal_name>",
  "internal_slug": "<internal_slug>",
  "template": "<template>",
  "calculation_group": 0,
  "priority": 0,
  "times_applicable_per_order": -1,
  "max_rewards": 1,
  "groups": [
    "default"
  ],
  "excluded_customers": [
    "customer@b2b.com"
  ],
  "simultaneity": [
    "default"
  ],
  "requirement_selection_type": "any",
  "reward_selection_type": "all",
  "currency_code": "gbp",
  "start_date": "2026-01-31T09:00:00Z",
  "end_date": "2026-01-31T09:00:00Z",
  "active": true,
  "requirements": [
    {
      "items": [
        {
          "restrictions": [
            {
              "type": "productSKU",
              "ref": "<ref>",
              "metadata_namespace": "erp",
              "metadata_key": "vendor"
            }
          ],
          "points_type": "line",
          "points": 1,
          "quantity": 0,
          "selection_type": "minimum"
        }
      ],
      "max_rewards": 0,
      "min_spend": 0,
      "max_spend": 0,
      "spend_tax_type": "net",
      "selection_type": "minimum",
      "min_points": 0
    }
  ],
  "rewards": [
    {
      "type": "requirements|all",
      "amount_type": "percent",
      "restriction_type": "equals",
      "item_id": "<item_id>",
      "metadata_namespace": "erp",
      "metadata_key": "vendor",
      "amount": 0
    }
  ],
  "other_requirements": [
    {
      "requirement_type": "coupons",
      "coupons": [
        {
          "code": "<code>"
        }
      ]
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Delete a discount

URL: https://docs.sparklayer.io/developers/api/core/delete-a-discount
Operation: `DELETE /api/v1/discounts/{id}` (operationId `deleteDiscount`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Deletes a discount so it no longer applies to carts or appears in the API, and returns `204`. Returns `404` if the discount doesn't exist.

`DELETE /api/v1/discounts/{id}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X DELETE "https://app.sparklayer.io/api/v1/discounts/942651af-f950-4716-9916-16170fe0645f" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The discount's ID (a UUID). Example: `942651af-f950-4716-9916-16170fe0645f` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 204: The discount was deleted. No body.

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Update a discount

URL: https://docs.sparklayer.io/developers/api/core/update-a-discount
Operation: `PATCH /api/v1/discounts/{id}` (operationId `updateDiscount`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Replaces the discount with the object you send, so include every required field, not just the ones you're changing. `internal_slug` can't be changed and must match the existing value, otherwise you get a `400`. The same currency, coupon code and size rules apply as when creating a discount, and an unknown ID returns `404`.

`PATCH /api/v1/discounts/{id}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PATCH "https://app.sparklayer.io/api/v1/discounts/942651af-f950-4716-9916-16170fe0645f" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "<name>",
  "internal_name": "<internal_name>",
  "internal_slug": "<internal_slug>",
  "template": "<template>",
  "calculation_group": 0,
  "priority": 0,
  "times_applicable_per_order": -1,
  "max_rewards": 1,
  "groups": [
    "default"
  ],
  "excluded_customers": [
    "customer@b2b.com"
  ],
  "simultaneity": [
    "default"
  ],
  "requirement_selection_type": "any",
  "reward_selection_type": "all",
  "currency_code": "gbp",
  "start_date": "2026-01-31T09:00:00Z",
  "end_date": "2026-01-31T09:00:00Z",
  "active": true,
  "requirements": [
    {
      "items": [
        {
          "restrictions": [
            {
              "type": "productSKU",
              "ref": "<ref>",
              "metadata_namespace": "erp",
              "metadata_key": "vendor"
            }
          ],
          "points_type": "line",
          "points": 1,
          "quantity": 0,
          "selection_type": "minimum"
        }
      ],
      "max_rewards": 0,
      "min_spend": 0,
      "max_spend": 0,
      "spend_tax_type": "net",
      "selection_type": "minimum",
      "min_points": 0
    }
  ],
  "rewards": [
    {
      "type": "requirements|all",
      "amount_type": "percent",
      "restriction_type": "equals",
      "item_id": "<item_id>",
      "metadata_namespace": "erp",
      "metadata_key": "vendor",
      "amount": 0
    }
  ],
  "other_requirements": [
    {
      "requirement_type": "coupons",
      "coupons": [
        {
          "code": "<code>"
        }
      ]
    }
  ]
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The discount's ID (a UUID). Example: `942651af-f950-4716-9916-16170fe0645f` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | | A user friendly name for the discount. Length: max 256. |
| `internal_name` | string | Yes | Length: max 45. |
| `internal_slug` | string | Yes | Length: max 45. |
| `template` | string \| null | | Discount template type. If not null allowed values are - 'order_level_get_amount_off', 'order_level_get_free_product', 'product_level_get_amount_off', 'order_level_get_shipping_reward', 'advanced_order_level_get_amount_off', 'order_level_requirement_amount_off', 'advanced_discount', 'advanced_free_products' |
| `calculation_group` | number | Yes | Dependency level = Calculation Group. All discounts with the same dependency level will share the same base, pre-discount totals. E.g. discount A (50% off) and discount B (50% off) will reward 100% off - not 75% off. Min 0, max 127. |
| `priority` | number | Yes | The sequence to apply the discounts (within each discount 'dependency level'). Min 0, max 10000. |
| `times_applicable_per_order` | number | Yes | Per order application limits. If -1 allow unlimited applications, otherwise limited. Min -1, max 127. |
| `max_rewards` | number \| null | | Used when rewardSelectionType is cheapest or expensive to determine the number of rewards available. Default: `1`. Min 1, max 127. |
| `groups` | string[] | Yes | Customer groups covered by this discount (use default to cover all groups) |
| `excluded_customers` | string[] | | Array of email address or accounting ids of customers to exclude from the discount |
| `simultaneity` | (string (uuid))[] \| null | | Other discounts which can be applied simultaneous, if null no limitation |
| `requirement_selection_type` | "any" \| "all" | Yes | Products which must be in the cart must match all or any one of the combo groups |
| `reward_selection_type` | "all" \| "cheapest" \| "expensive" | Yes | |
| `currency_code` | string \| null | Yes | Length: min 3, max 3. |
| `start_date` | string (date-time) \| null | Yes | Start Date |
| `end_date` | string (date-time) \| null | Yes | End Date |
| `active` | boolean | Yes | |
| `requirements` | object[] | Yes | |
| `requirements[].items` | object[] | Yes | |
| `requirements[].items[].restrictions` | object[] | Yes | |
| `requirements[].items[].restrictions[].type` | "productSKU" \| "excludeProductSKU" \| "productSKUContains" \| "excludeProductSKUContains" \| "productMetadata" \| "excludeProductMetadata" | Yes | |
| `requirements[].items[].restrictions[].ref` | string | Yes | |
| `requirements[].items[].restrictions[].metadata_namespace` | string \| null | | Length: max 256. |
| `requirements[].items[].restrictions[].metadata_key` | string \| null | | Length: max 128. |
| `requirements[].items[].points_type` | "line" \| "item" | Yes | Add X point(s) for each matching product OR Add X point(s) for once only |
| `requirements[].items[].points` | integer | Yes | Default: `1`. |
| `requirements[].items[].quantity` | integer | Yes | |
| `requirements[].items[].selection_type` | "minimum" \| "exact" | Yes | At least X quantity of product(s) must match OR Exactly X quantity of product(s) |
| `requirements[].max_rewards` | integer \| null | Yes | Limit the number of rewards when this requirement applies |
| `requirements[].min_spend` | number \| null | Yes | The cart must contain between min_spend and max_spend based on spend_tax_type of the requirement. |
| `requirements[].max_spend` | number \| null | Yes | |
| `requirements[].spend_tax_type` | "net" | Yes | |
| `requirements[].selection_type` | "minimum" \| "all" | Yes | Apply only if 'all' items matched in the cart OR if cart worth minimum of min_points requirement items(s) using requirements |
| `requirements[].min_points` | integer \| null | Yes | Only applies when selection_type is minimum |
| `rewards` | object[] | | |
| `rewards[].type` | "requirements\|all" \| "requirements\|cheapest" \| "cart\|productSKU" \| "cart\|cheapestProductSKU" \| "cart\|productMetadata" \| "cart\|cheapestProductMetadata" \| "product" \| "shipping" \| "order" | Yes | |
| `rewards[].amount_type` | "percent" \| "percentPreDiscount" \| "priceAllGross" \| "priceAllNet" \| "priceLineGross" \| "priceLineNet" \| "fixedAllGross" \| "fixedAllNet" \| "fixedLineGross" \| "fixedLineNet" \| "none" | Yes | |
| `rewards[].restriction_type` | "equals" \| "notEquals" \| "contains" \| "notContains" | | |
| `rewards[].item_id` | string | Yes | Length: max 100. |
| `rewards[].metadata_namespace` | string \| null | | Length: max 256. |
| `rewards[].metadata_key` | string \| null | | Length: max 128. |
| `rewards[].amount` | number | Yes | Max 1000000000. |
| `other_requirements` | (Discount.OtherRequirements.Coupons \| Discount.OtherRequirements.NumItems \| Discount.OtherRequirements.SpendAmount \| Discount.OtherRequirements.MaxUsesPerCustomer)[] | Yes | |
| `other_requirements[].requirement_type` | "coupons" | | |
| `other_requirements[].coupons` | object[] | | Items: min 1. |
| `other_requirements[].coupons[].code` | string | | |
| `other_requirements[].min` | number \| null | | |
| `other_requirements[].max` | number \| null | | |
| `other_requirements[].type` | "productsTotalItems" \| "productsTotalQuantity" | | |
| `other_requirements[].tax_type` | "net" | | |
| `other_requirements[].number` | number | | |

```json
{
  "name": "<name>",
  "internal_name": "<internal_name>",
  "internal_slug": "<internal_slug>",
  "template": "<template>",
  "calculation_group": 0,
  "priority": 0,
  "times_applicable_per_order": -1,
  "max_rewards": 1,
  "groups": [
    "default"
  ],
  "excluded_customers": [
    "customer@b2b.com"
  ],
  "simultaneity": [
    "default"
  ],
  "requirement_selection_type": "any",
  "reward_selection_type": "all",
  "currency_code": "gbp",
  "start_date": "2026-01-31T09:00:00Z",
  "end_date": "2026-01-31T09:00:00Z",
  "active": true,
  "requirements": [
    {
      "items": [
        {
          "restrictions": [
            {
              "type": "productSKU",
              "ref": "<ref>",
              "metadata_namespace": "erp",
              "metadata_key": "vendor"
            }
          ],
          "points_type": "line",
          "points": 1,
          "quantity": 0,
          "selection_type": "minimum"
        }
      ],
      "max_rewards": 0,
      "min_spend": 0,
      "max_spend": 0,
      "spend_tax_type": "net",
      "selection_type": "minimum",
      "min_points": 0
    }
  ],
  "rewards": [
    {
      "type": "requirements|all",
      "amount_type": "percent",
      "restriction_type": "equals",
      "item_id": "<item_id>",
      "metadata_namespace": "erp",
      "metadata_key": "vendor",
      "amount": 0
    }
  ],
  "other_requirements": [
    {
      "requirement_type": "coupons",
      "coupons": [
        {
          "code": "<code>"
        }
      ]
    }
  ]
}
```

### Responses

#### 200: The updated discount.

The `Discount` object: the request body's fields, plus:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | | Discount ID (uuid) |
| `created_at` | string (date-time) | | |
| `deleted_at` | string (date-time) \| null | | |
| `updated_at` | string (date-time) | | |

```json
{
  "id": "942651af-f950-4716-9916-16170fe0645f",
  "created_at": "2026-01-31T09:00:00Z",
  "deleted_at": "2026-01-31T09:00:00Z",
  "updated_at": "2026-01-31T09:00:00Z",
  "name": "<name>",
  "internal_name": "<internal_name>",
  "internal_slug": "<internal_slug>",
  "template": "<template>",
  "calculation_group": 0,
  "priority": 0,
  "times_applicable_per_order": -1,
  "max_rewards": 1,
  "groups": [
    "default"
  ],
  "excluded_customers": [
    "customer@b2b.com"
  ],
  "simultaneity": [
    "default"
  ],
  "requirement_selection_type": "any",
  "reward_selection_type": "all",
  "currency_code": "gbp",
  "start_date": "2026-01-31T09:00:00Z",
  "end_date": "2026-01-31T09:00:00Z",
  "active": true,
  "requirements": [
    {
      "items": [
        {
          "restrictions": [
            {
              "type": "productSKU",
              "ref": "<ref>",
              "metadata_namespace": "erp",
              "metadata_key": "vendor"
            }
          ],
          "points_type": "line",
          "points": 1,
          "quantity": 0,
          "selection_type": "minimum"
        }
      ],
      "max_rewards": 0,
      "min_spend": 0,
      "max_spend": 0,
      "spend_tax_type": "net",
      "selection_type": "minimum",
      "min_points": 0
    }
  ],
  "rewards": [
    {
      "type": "requirements|all",
      "amount_type": "percent",
      "restriction_type": "equals",
      "item_id": "<item_id>",
      "metadata_namespace": "erp",
      "metadata_key": "vendor",
      "amount": 0
    }
  ],
  "other_requirements": [
    {
      "requirement_type": "coupons",
      "coupons": [
        {
          "code": "<code>"
        }
      ]
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# List shipping methods

URL: https://docs.sparklayer.io/developers/api/core/list-of-shipping-methods
Operation: `GET /api/v1/shipping-methods` (operationId `listOfShippingMethods`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Returns every shipping method configured for the store, including its bands, as a single array. Methods aren't filtered by country, customer group or cart contents, and the list isn't paginated.

`GET /api/v1/shipping-methods`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/shipping-methods" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: Every shipping method, including its bands.

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].id` | string | | Shipping Method ID (always prefixed with sm_). Length: max 15. |
| `[].created_at` | string (date-time) | | Created At |
| `[].updated_at` | string (date-time) | | Updated At |
| `[].sku` | string | | Shipping SKU. Length: max 50. |
| `[].title` | string | | Shiping Method Name shown at checkout. Length: max 50. |
| `[].priority` | number | | Shown by order (lower first). Default: `0`. Min 0, max 127. |
| `[].countries` | string[] | | Countries covered by this shipping method (ISO 3166-1 alpha-2) |
| `[].regions` | object | | Regions covered by this shipping method (per country) Keys are country codes (ISO 3166-1 alpha-2) Values are lists of region codes. If the list is empty, all regions are allowed |
| `[].groups` | string[] | | Customer groups covered by this shipping method (use default to cover all groups) |
| `[].bands` | object[] | | |
| `[].bands[].name` | string | | Internal Band Name. Length: max 50. |
| `[].bands[].priority` | number | | Filtered by first found by percentage_charge order (lower first). Default: `0`. Min 0, max 127. |
| `[].bands[].sku` | string \| null | | Shipping SKU (Leave null to use the Shipping Method SKU). Length: max 15. |
| `[].bands[].requirement` | ShippingMethod.Requirement.Weight \| ShippingMethod.Requirement.GrossTotal \| ShippingMethod.Requirement.NetTotal \| ShippingMethod.Requirement.None | | The band is selected based on the requirement. |
| `[].bands[].cost` | ShippingMethod.Cost.Free \| ShippingMethod.Cost.FixedCost \| ShippingMethod.Cost.PercentNetTotal \| ShippingMethod.Cost.Custom | | |

```json
[
  {
    "id": "sm_123",
    "created_at": "2026-01-31T09:00:00Z",
    "updated_at": "2026-01-31T09:00:00Z",
    "sku": "SKU001",
    "title": "Standard Shipping",
    "priority": 0,
    "countries": [
      "GB"
    ],
    "regions": {},
    "groups": [
      "default"
    ],
    "bands": [
      {
        "name": "Band 1",
        "priority": 0,
        "sku": "ship_123",
        "requirement": {
          "type": "weight",
          "min": 0,
          "max": 0
        },
        "cost": {
          "type": "free"
        }
      }
    ]
  }
]
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Create a shipping method

URL: https://docs.sparklayer.io/developers/api/core/create-a-shipping-method
Operation: `POST /api/v1/shipping-methods` (operationId `createShippingMethod`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Creates a shipping method, including its bands, and returns it with its `sm_`-prefixed ID. The `sku` must be unique across shipping methods; a duplicate returns `400` (`duplicate-sku`).

`POST /api/v1/shipping-methods`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/shipping-methods" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "sku": "SKU001",
  "title": "Standard Shipping",
  "priority": 0,
  "countries": [
    "GB"
  ],
  "regions": {},
  "groups": [
    "default"
  ],
  "bands": [
    {
      "name": "Band 1",
      "priority": 0,
      "sku": "ship_123",
      "requirement": {
        "type": "weight",
        "min": 0,
        "max": 0
      },
      "cost": {
        "type": "free"
      }
    }
  ]
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `sku` | string | Yes | Shipping SKU. Length: max 50. |
| `title` | string | Yes | Shiping Method Name shown at checkout. Length: max 50. |
| `priority` | number | | Shown by order (lower first). Default: `0`. Min 0, max 127. |
| `countries` | string[] | Yes | Countries covered by this shipping method (ISO 3166-1 alpha-2) |
| `regions` | object | | Regions covered by this shipping method (per country) Keys are country codes (ISO 3166-1 alpha-2) Values are lists of region codes. If the list is empty, all regions are allowed |
| `groups` | string[] | | Customer groups covered by this shipping method (use default to cover all groups) |
| `bands` | object[] | | |
| `bands[].name` | string | | Internal Band Name. Length: max 50. |
| `bands[].priority` | number | | Filtered by first found by percentage_charge order (lower first). Default: `0`. Min 0, max 127. |
| `bands[].sku` | string \| null | | Shipping SKU (Leave null to use the Shipping Method SKU). Length: max 15. |
| `bands[].requirement` | ShippingMethod.Requirement.Weight \| ShippingMethod.Requirement.GrossTotal \| ShippingMethod.Requirement.NetTotal \| ShippingMethod.Requirement.None | | The band is selected based on the requirement. |
| `bands[].cost` | ShippingMethod.Cost.Free \| ShippingMethod.Cost.FixedCost \| ShippingMethod.Cost.PercentNetTotal \| ShippingMethod.Cost.Custom | | |

```json
{
  "sku": "SKU001",
  "title": "Standard Shipping",
  "priority": 0,
  "countries": [
    "GB"
  ],
  "regions": {},
  "groups": [
    "default"
  ],
  "bands": [
    {
      "name": "Band 1",
      "priority": 0,
      "sku": "ship_123",
      "requirement": {
        "type": "weight",
        "min": 0,
        "max": 0
      },
      "cost": {
        "type": "free"
      }
    }
  ]
}
```

### Responses

#### 200: The new shipping method, including its `sm_`-prefixed `id`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | | Shipping Method ID (always prefixed with sm_). Length: max 15. |
| `created_at` | string (date-time) | | Created At |
| `updated_at` | string (date-time) | | Updated At |
| `sku` | string | | Shipping SKU. Length: max 50. |
| `title` | string | | Shiping Method Name shown at checkout. Length: max 50. |
| `priority` | number | | Shown by order (lower first). Default: `0`. Min 0, max 127. |
| `countries` | string[] | | Countries covered by this shipping method (ISO 3166-1 alpha-2) |
| `regions` | object | | Regions covered by this shipping method (per country) Keys are country codes (ISO 3166-1 alpha-2) Values are lists of region codes. If the list is empty, all regions are allowed |
| `groups` | string[] | | Customer groups covered by this shipping method (use default to cover all groups) |
| `bands` | object[] | | |
| `bands[].name` | string | | Internal Band Name. Length: max 50. |
| `bands[].priority` | number | | Filtered by first found by percentage_charge order (lower first). Default: `0`. Min 0, max 127. |
| `bands[].sku` | string \| null | | Shipping SKU (Leave null to use the Shipping Method SKU). Length: max 15. |
| `bands[].requirement` | ShippingMethod.Requirement.Weight \| ShippingMethod.Requirement.GrossTotal \| ShippingMethod.Requirement.NetTotal \| ShippingMethod.Requirement.None | | The band is selected based on the requirement. |
| `bands[].cost` | ShippingMethod.Cost.Free \| ShippingMethod.Cost.FixedCost \| ShippingMethod.Cost.PercentNetTotal \| ShippingMethod.Cost.Custom | | |

```json
{
  "id": "sm_123",
  "created_at": "2026-01-31T09:00:00Z",
  "updated_at": "2026-01-31T09:00:00Z",
  "sku": "SKU001",
  "title": "Standard Shipping",
  "priority": 0,
  "countries": [
    "GB"
  ],
  "regions": {},
  "groups": [
    "default"
  ],
  "bands": [
    {
      "name": "Band 1",
      "priority": 0,
      "sku": "ship_123",
      "requirement": {
        "type": "weight",
        "min": 0,
        "max": 0
      },
      "cost": {
        "type": "free"
      }
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Get a shipping method

URL: https://docs.sparklayer.io/developers/api/core/get-a-shipping-method
Operation: `GET /api/v1/shipping-methods/{id}` (operationId `getShippingMethod`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Returns a single shipping method by its `sm_`-prefixed ID. Returns `404` if the shipping method doesn't exist.

`GET /api/v1/shipping-methods/{id}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/shipping-methods/sm_123" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The shipping method's ID, prefixed with `sm_`. Example: `sm_123` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: The shipping method.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | | Shipping Method ID (always prefixed with sm_). Length: max 15. |
| `created_at` | string (date-time) | | Created At |
| `updated_at` | string (date-time) | | Updated At |
| `sku` | string | | Shipping SKU. Length: max 50. |
| `title` | string | | Shiping Method Name shown at checkout. Length: max 50. |
| `priority` | number | | Shown by order (lower first). Default: `0`. Min 0, max 127. |
| `countries` | string[] | | Countries covered by this shipping method (ISO 3166-1 alpha-2) |
| `regions` | object | | Regions covered by this shipping method (per country) Keys are country codes (ISO 3166-1 alpha-2) Values are lists of region codes. If the list is empty, all regions are allowed |
| `groups` | string[] | | Customer groups covered by this shipping method (use default to cover all groups) |
| `bands` | object[] | | |
| `bands[].name` | string | | Internal Band Name. Length: max 50. |
| `bands[].priority` | number | | Filtered by first found by percentage_charge order (lower first). Default: `0`. Min 0, max 127. |
| `bands[].sku` | string \| null | | Shipping SKU (Leave null to use the Shipping Method SKU). Length: max 15. |
| `bands[].requirement` | ShippingMethod.Requirement.Weight \| ShippingMethod.Requirement.GrossTotal \| ShippingMethod.Requirement.NetTotal \| ShippingMethod.Requirement.None | | The band is selected based on the requirement. |
| `bands[].cost` | ShippingMethod.Cost.Free \| ShippingMethod.Cost.FixedCost \| ShippingMethod.Cost.PercentNetTotal \| ShippingMethod.Cost.Custom | | |

```json
{
  "id": "sm_123",
  "created_at": "2026-01-31T09:00:00Z",
  "updated_at": "2026-01-31T09:00:00Z",
  "sku": "SKU001",
  "title": "Standard Shipping",
  "priority": 0,
  "countries": [
    "GB"
  ],
  "regions": {},
  "groups": [
    "default"
  ],
  "bands": [
    {
      "name": "Band 1",
      "priority": 0,
      "sku": "ship_123",
      "requirement": {
        "type": "weight",
        "min": 0,
        "max": 0
      },
      "cost": {
        "type": "free"
      }
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Delete a shipping method

URL: https://docs.sparklayer.io/developers/api/core/delete-a-shipping-method
Operation: `DELETE /api/v1/shipping-methods/{id}` (operationId `deleteShippingMethod`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Permanently deletes a shipping method along with its bands, costs and platform mappings, and returns `204`. Returns `404` if the shipping method doesn't exist.

`DELETE /api/v1/shipping-methods/{id}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X DELETE "https://app.sparklayer.io/api/v1/shipping-methods/sm_123" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The shipping method's ID, prefixed with `sm_`. Example: `sm_123` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 204: The shipping method was deleted. No body.

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Update a shipping method

URL: https://docs.sparklayer.io/developers/api/core/update-a-shipping-method
Operation: `PATCH /api/v1/shipping-methods/{id}` (operationId `updateShippingMethod`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Updates a shipping method and returns it. Fields you omit keep their current values, but if you send `bands` the list replaces all existing bands. Returns `404` if the shipping method doesn't exist.

`PATCH /api/v1/shipping-methods/{id}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PATCH "https://app.sparklayer.io/api/v1/shipping-methods/sm_123" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "sku": "SKU001",
  "title": "Standard Shipping",
  "priority": 0,
  "countries": [
    "GB"
  ],
  "regions": {},
  "groups": [
    "default"
  ],
  "bands": [
    {
      "name": "Band 1",
      "priority": 0,
      "sku": "ship_123",
      "requirement": {
        "type": "weight",
        "min": 0,
        "max": 0
      },
      "cost": {
        "type": "free"
      }
    }
  ]
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The shipping method's ID, prefixed with `sm_`. Example: `sm_123` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `sku` | string | | Shipping SKU. Length: max 50. |
| `title` | string | | Shiping Method Name shown at checkout. Length: max 50. |
| `priority` | number | | Shown by order (lower first). Default: `0`. Min 0, max 127. |
| `countries` | string[] | | Countries covered by this shipping method (ISO 3166-1 alpha-2) |
| `regions` | object | | Regions covered by this shipping method (per country) Keys are country codes (ISO 3166-1 alpha-2) Values are lists of region codes. If the list is empty, all regions are allowed |
| `groups` | string[] | | Customer groups covered by this shipping method (use default to cover all groups) |
| `bands` | object[] | | |
| `bands[].name` | string | | Internal Band Name. Length: max 50. |
| `bands[].priority` | number | | Filtered by first found by percentage_charge order (lower first). Default: `0`. Min 0, max 127. |
| `bands[].sku` | string \| null | | Shipping SKU (Leave null to use the Shipping Method SKU). Length: max 15. |
| `bands[].requirement` | ShippingMethod.Requirement.Weight \| ShippingMethod.Requirement.GrossTotal \| ShippingMethod.Requirement.NetTotal \| ShippingMethod.Requirement.None | | The band is selected based on the requirement. |
| `bands[].cost` | ShippingMethod.Cost.Free \| ShippingMethod.Cost.FixedCost \| ShippingMethod.Cost.PercentNetTotal \| ShippingMethod.Cost.Custom | | |

```json
{
  "sku": "SKU001",
  "title": "Standard Shipping",
  "priority": 0,
  "countries": [
    "GB"
  ],
  "regions": {},
  "groups": [
    "default"
  ],
  "bands": [
    {
      "name": "Band 1",
      "priority": 0,
      "sku": "ship_123",
      "requirement": {
        "type": "weight",
        "min": 0,
        "max": 0
      },
      "cost": {
        "type": "free"
      }
    }
  ]
}
```

### Responses

#### 200: The updated shipping method.

The `ShippingMethod` object: the request body's fields, plus:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | | Shipping Method ID (always prefixed with sm_). Length: max 15. |
| `created_at` | string (date-time) | | Created At |
| `updated_at` | string (date-time) | | Updated At |

```json
{
  "id": "sm_123",
  "created_at": "2026-01-31T09:00:00Z",
  "updated_at": "2026-01-31T09:00:00Z",
  "sku": "SKU001",
  "title": "Standard Shipping",
  "priority": 0,
  "countries": [
    "GB"
  ],
  "regions": {},
  "groups": [
    "default"
  ],
  "bands": [
    {
      "name": "Band 1",
      "priority": 0,
      "sku": "ship_123",
      "requirement": {
        "type": "weight",
        "min": 0,
        "max": 0
      },
      "cost": {
        "type": "free"
      }
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# List global settings

URL: https://docs.sparklayer.io/developers/api/core/list-global-settings
Operation: `GET /api/v1/settings` (operationId `listGlobalSettings`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Lists Global settings (minus settings which include authentication details)

`GET /api/v1/settings`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/settings" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: The store-wide settings, as `key`/`value` pairs.

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | string | Yes | |
| `[].value` | any \| null | Yes | |

```json
[
  {
    "key": "<key>",
    "value": null
  }
]
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Update global settings

URL: https://docs.sparklayer.io/developers/api/core/update-global-setting
Operation: `PATCH /api/v1/settings` (operationId `patchGlobalSetting`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Updates one or more store-wide settings, sent as an array of `key`/`value` pairs, and returns `204`. Only a fixed set of setting keys can be updated.

API keys created in the SparkLayer Dashboard can't update global settings: the request is rejected with the message "Global settings unavailable for updates, please contact support". Contact support if you need to change them.

`PATCH /api/v1/settings`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PATCH "https://app.sparklayer.io/api/v1/settings" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "key": "<key>",
    "value": null
  }
]'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | string | Yes | |
| `[].value` | any \| null | Yes | |

```json
[
  {
    "key": "<key>",
    "value": null
  }
]
```

### Responses

#### 204: The settings were updated. No body.

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# List customer group settings

URL: https://docs.sparklayer.io/developers/api/core/list-customer-group-settings
Operation: `GET /api/v1/settings/{slug}` (operationId `listSettings`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Lists Customer Group settings by Customer Group

`GET /api/v1/settings/{slug}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/settings/eu_gbp" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | The customer group's slug, as returned by **List customer groups** (for example `eu_gbp`). Example: `eu_gbp` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: The customer group's settings, as `key`/`value` pairs.

An array. Each item is one of these:

**Settings.orderTotalsValidation**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "orderTotalsValidation" | Yes | |
| `[].value` | object[] \| null | Yes | |
| `[].value[].currency_code` | string | Yes | [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code. Length: min 3, max 3. |
| `[].value[].minimum_value` | number | Yes | Min 0. |
| `[].value[].maximum_value` | number \| null | | Min 0. |
| `[].value[].compare_type` | "gross" \| "net" | Yes | |

**Settings.orderItemQuantityValidation**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "orderItemQuantityValidation" | Yes | |
| `[].value` | object \| null | Yes | |
| `[].value.minimum_quantity` | number \| null | | Min 1. |
| `[].value.maximum_quantity` | number \| null | | Min 1. |

**Settings.priceListSelection**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "priceListSelection" | Yes | |
| `[].value` | object[] \| null | Yes | |
| `[].value[].price_list_slug` | string | Yes | Price List Slug |

**Settings.allowedPaymentMethods**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "allowedPaymentMethods" | Yes | |
| `[].value` | object \| null | Yes | |
| `[].value.payment_by_invoice` | boolean | | |
| `[].value.payment_on_account` | boolean | | |
| `[].value.upfront_payment` | boolean | | |
| `[].value.quote` | boolean | | |

**Settings.paymentRules**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "paymentRules" | Yes | |
| `[].value` | object \| null | Yes | The customer group's own payment rules, or null when it has none and inherits its nearest ancestor's. Send null through PATCH to drop an override and inherit again. At most 5 rules per method. |
| `[].value.payment_by_invoice` | object[] | | Items: max 5. |
| `[].value.payment_by_invoice[].conditions` | object | Yes | Conditions the rule narrows itself by, keyed by what each one matches on so a rule cannot carry two of the same. All present conditions must match. A rule with no conditions applies to every order. Money bounds are in the currency of the price list the cart is priced in. |
| `[].value.payment_by_invoice[].conditions.order_total` | object | | The net order total must fall within these bounds |
| `[].value.payment_by_invoice[].conditions.order_total.minimum` | number (double) \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_by_invoice[].conditions.order_total.maximum` | number (double) \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_by_invoice[].conditions.order_quantity` | object | | The size of the order must fall within these bounds |
| `[].value.payment_by_invoice[].conditions.order_quantity.type` | "total_quantity" \| "line_items" | Yes | What is counted: `total_quantity` sums the units across every line, `line_items` counts the lines themselves. |
| `[].value.payment_by_invoice[].conditions.order_quantity.minimum` | integer \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_by_invoice[].conditions.order_quantity.maximum` | integer \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_by_invoice[].conditions.available_credit` | object | | The credit the customer has left to spend must fall within these bounds. This is credit remaining, not the total credit limit. A customer with no credit limit set has unlimited credit and satisfies any minimum. |
| `[].value.payment_by_invoice[].conditions.available_credit.minimum` | number (double) \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_by_invoice[].conditions.available_credit.maximum` | number (double) \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_by_invoice[].conditions.products` | object | | Matches when a product in the cart satisfies any one of the filters. Filters are OR'd, and may mix SKU and metadata. |
| `[].value.payment_by_invoice[].conditions.products.filters` | (PaymentRule.Products.Sku \| PaymentRule.Products.Metadata)[] | Yes | Items: min 1, max 25. |
| `[].value.payment_by_invoice[].conditions.products.filters[].type` | "sku" | | |
| `[].value.payment_by_invoice[].conditions.products.filters[].value` | string | | Length: min 1. |
| `[].value.payment_by_invoice[].conditions.products.filters[].metadata_namespace` | string | | Length: min 1, max 256. |
| `[].value.payment_by_invoice[].conditions.products.filters[].metadata_key` | string | | Length: min 1, max 128. |
| `[].value.payment_by_invoice[].outcome` | PaymentRule.Outcome.Surcharge \| PaymentRule.Outcome.Discount \| PaymentRule.Outcome.Hide | Yes | What happens to the payment method when every condition matches |
| `[].value.payment_on_account` | object[] | | Items: max 5. |
| `[].value.payment_on_account[].conditions` | object | Yes | Conditions the rule narrows itself by, keyed by what each one matches on so a rule cannot carry two of the same. All present conditions must match. A rule with no conditions applies to every order. Money bounds are in the currency of the price list the cart is priced in. |
| `[].value.payment_on_account[].conditions.order_total` | object | | The net order total must fall within these bounds |
| `[].value.payment_on_account[].conditions.order_total.minimum` | number (double) \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_on_account[].conditions.order_total.maximum` | number (double) \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_on_account[].conditions.order_quantity` | object | | The size of the order must fall within these bounds |
| `[].value.payment_on_account[].conditions.order_quantity.type` | "total_quantity" \| "line_items" | Yes | What is counted: `total_quantity` sums the units across every line, `line_items` counts the lines themselves. |
| `[].value.payment_on_account[].conditions.order_quantity.minimum` | integer \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_on_account[].conditions.order_quantity.maximum` | integer \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_on_account[].conditions.available_credit` | object | | The credit the customer has left to spend must fall within these bounds. This is credit remaining, not the total credit limit. A customer with no credit limit set has unlimited credit and satisfies any minimum. |
| `[].value.payment_on_account[].conditions.available_credit.minimum` | number (double) \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_on_account[].conditions.available_credit.maximum` | number (double) \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_on_account[].conditions.products` | object | | Matches when a product in the cart satisfies any one of the filters. Filters are OR'd, and may mix SKU and metadata. |
| `[].value.payment_on_account[].conditions.products.filters` | (PaymentRule.Products.Sku \| PaymentRule.Products.Metadata)[] | Yes | Items: min 1, max 25. |
| `[].value.payment_on_account[].conditions.products.filters[].type` | "sku" | | |
| `[].value.payment_on_account[].conditions.products.filters[].value` | string | | Length: min 1. |
| `[].value.payment_on_account[].conditions.products.filters[].metadata_namespace` | string | | Length: min 1, max 256. |
| `[].value.payment_on_account[].conditions.products.filters[].metadata_key` | string | | Length: min 1, max 128. |
| `[].value.payment_on_account[].outcome` | PaymentRule.Outcome.Surcharge \| PaymentRule.Outcome.Discount \| PaymentRule.Outcome.Hide | Yes | What happens to the payment method when every condition matches |
| `[].value.upfront_payment` | object[] | | Items: max 5. |
| `[].value.upfront_payment[].conditions` | object | Yes | Conditions the rule narrows itself by, keyed by what each one matches on so a rule cannot carry two of the same. All present conditions must match. A rule with no conditions applies to every order. Money bounds are in the currency of the price list the cart is priced in. |
| `[].value.upfront_payment[].conditions.order_total` | object | | The net order total must fall within these bounds |
| `[].value.upfront_payment[].conditions.order_total.minimum` | number (double) \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.upfront_payment[].conditions.order_total.maximum` | number (double) \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.upfront_payment[].conditions.order_quantity` | object | | The size of the order must fall within these bounds |
| `[].value.upfront_payment[].conditions.order_quantity.type` | "total_quantity" \| "line_items" | Yes | What is counted: `total_quantity` sums the units across every line, `line_items` counts the lines themselves. |
| `[].value.upfront_payment[].conditions.order_quantity.minimum` | integer \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.upfront_payment[].conditions.order_quantity.maximum` | integer \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.upfront_payment[].conditions.available_credit` | object | | The credit the customer has left to spend must fall within these bounds. This is credit remaining, not the total credit limit. A customer with no credit limit set has unlimited credit and satisfies any minimum. |
| `[].value.upfront_payment[].conditions.available_credit.minimum` | number (double) \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.upfront_payment[].conditions.available_credit.maximum` | number (double) \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.upfront_payment[].conditions.products` | object | | Matches when a product in the cart satisfies any one of the filters. Filters are OR'd, and may mix SKU and metadata. |
| `[].value.upfront_payment[].conditions.products.filters` | (PaymentRule.Products.Sku \| PaymentRule.Products.Metadata)[] | Yes | Items: min 1, max 25. |
| `[].value.upfront_payment[].conditions.products.filters[].type` | "sku" | | |
| `[].value.upfront_payment[].conditions.products.filters[].value` | string | | Length: min 1. |
| `[].value.upfront_payment[].conditions.products.filters[].metadata_namespace` | string | | Length: min 1, max 256. |
| `[].value.upfront_payment[].conditions.products.filters[].metadata_key` | string | | Length: min 1, max 128. |
| `[].value.upfront_payment[].outcome` | PaymentRule.Outcome.Surcharge \| PaymentRule.Outcome.Discount \| PaymentRule.Outcome.Hide | Yes | What happens to the payment method when every condition matches |
| `[].value.quote` | object[] | | Rules for the legacy request-for-quote payment method. The newer quoting system is a purchase type rather than a payment method, so it carries no rules. Items: max 5. |
| `[].value.quote[].conditions` | object | Yes | Conditions the rule narrows itself by, keyed by what each one matches on so a rule cannot carry two of the same. All present conditions must match. A rule with no conditions applies to every order. Money bounds are in the currency of the price list the cart is priced in. |
| `[].value.quote[].conditions.order_total` | object | | The net order total must fall within these bounds |
| `[].value.quote[].conditions.order_total.minimum` | number (double) \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.quote[].conditions.order_total.maximum` | number (double) \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.quote[].conditions.order_quantity` | object | | The size of the order must fall within these bounds |
| `[].value.quote[].conditions.order_quantity.type` | "total_quantity" \| "line_items" | Yes | What is counted: `total_quantity` sums the units across every line, `line_items` counts the lines themselves. |
| `[].value.quote[].conditions.order_quantity.minimum` | integer \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.quote[].conditions.order_quantity.maximum` | integer \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.quote[].conditions.available_credit` | object | | The credit the customer has left to spend must fall within these bounds. This is credit remaining, not the total credit limit. A customer with no credit limit set has unlimited credit and satisfies any minimum. |
| `[].value.quote[].conditions.available_credit.minimum` | number (double) \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.quote[].conditions.available_credit.maximum` | number (double) \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.quote[].conditions.products` | object | | Matches when a product in the cart satisfies any one of the filters. Filters are OR'd, and may mix SKU and metadata. |
| `[].value.quote[].conditions.products.filters` | (PaymentRule.Products.Sku \| PaymentRule.Products.Metadata)[] | Yes | Items: min 1, max 25. |
| `[].value.quote[].conditions.products.filters[].type` | "sku" | | |
| `[].value.quote[].conditions.products.filters[].value` | string | | Length: min 1. |
| `[].value.quote[].conditions.products.filters[].metadata_namespace` | string | | Length: min 1, max 256. |
| `[].value.quote[].conditions.products.filters[].metadata_key` | string | | Length: min 1, max 128. |
| `[].value.quote[].outcome` | PaymentRule.Outcome.Surcharge \| PaymentRule.Outcome.Discount \| PaymentRule.Outcome.Hide | Yes | What happens to the payment method when every condition matches |

**Settings.allowAddressEditing**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "allowAddressEditing" | Yes | |
| `[].value` | boolean \| null | Yes | |

**Settings.allowDefaultBillingModification**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "allowDefaultBillingModification" | Yes | |
| `[].value` | boolean \| null | Yes | |

**Settings.paymentOnAccountEnforceCreditLimit**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "paymentOnAccountEnforceCreditLimit" | Yes | |
| `[].value` | boolean \| null | Yes | |

**Settings.useMultiLocationStock**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "useMultiLocationStock" | Yes | |
| `[].value` | boolean \| null | Yes | |

**Settings.multiLocationStockConfig**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "multiLocationStockConfig" | Yes | |
| `[].value` | object \| null | Yes | |
| `[].value.useDefault` | boolean | | |
| `[].value.allowedStockLocationIds` | (string (uuid))[] | | |

**Settings.stockDisplay**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "stockDisplay" | Yes | |
| `[].value` | object \| null | Yes | |
| `[].value.show_status` | boolean | | |
| `[].value.show_units` | boolean | | |
| `[].value.max` | integer | | |
| `[].value.low` | integer | | |
| `[].value.last` | integer | | |

**Settings.quotingEngine**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "quotingEngine" | Yes | |
| `[].value` | object \| null | Yes | |
| `[].value.customer_create_quote` | boolean | | |

**Settings.allowCheckout**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "allowCheckout" | Yes | |
| `[].value` | boolean \| null | Yes | |

**Settings.recurringOrdersEngine**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "recurringOrdersEngine" | Yes | |
| `[].value` | object \| null | Yes | |
| `[].value.customer_create_recurring_orders` | boolean | | |

```json
[
  {
    "key": "orderTotalsValidation",
    "value": [
      {
        "currency_code": "gbp",
        "minimum_value": 0,
        "maximum_value": 0,
        "compare_type": "gross"
      }
    ]
  }
]
```

#### 404: Customer group not found

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Update customer group settings

URL: https://docs.sparklayer.io/developers/api/core/update-customer-group-setting
Operation: `PATCH /api/v1/settings/{slug}` (operationId `patchCustomerGroupSetting`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Updates one or more settings for the customer group identified by `slug`, sent as an array of `key`/`value` pairs, and returns `204`. Only customer group settings can be set here, for example `allowCheckout`, `allowedPaymentMethods`, `paymentRules`, `priceListSelection` and `orderTotalsValidation`.

`PATCH /api/v1/settings/{slug}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PATCH "https://app.sparklayer.io/api/v1/settings/eu_gbp" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "key": "orderTotalsValidation",
    "value": [
      {
        "currency_code": "gbp",
        "minimum_value": 0,
        "maximum_value": 0,
        "compare_type": "gross"
      }
    ]
  }
]'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | The customer group's slug, as returned by **List customer groups** (for example `eu_gbp`). Example: `eu_gbp` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

An array. Each item is one of these:

**Settings.orderTotalsValidation**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "orderTotalsValidation" | Yes | |
| `[].value` | object[] \| null | Yes | |
| `[].value[].currency_code` | string | Yes | [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code. Length: min 3, max 3. |
| `[].value[].minimum_value` | number | Yes | Min 0. |
| `[].value[].maximum_value` | number \| null | | Min 0. |
| `[].value[].compare_type` | "gross" \| "net" | Yes | |

**Settings.orderItemQuantityValidation**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "orderItemQuantityValidation" | Yes | |
| `[].value` | object \| null | Yes | |
| `[].value.minimum_quantity` | number \| null | | Min 1. |
| `[].value.maximum_quantity` | number \| null | | Min 1. |

**Settings.priceListSelection**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "priceListSelection" | Yes | |
| `[].value` | object[] \| null | Yes | |
| `[].value[].price_list_slug` | string | Yes | Price List Slug |

**Settings.allowedPaymentMethods**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "allowedPaymentMethods" | Yes | |
| `[].value` | object \| null | Yes | |
| `[].value.payment_by_invoice` | boolean | | |
| `[].value.payment_on_account` | boolean | | |
| `[].value.upfront_payment` | boolean | | |
| `[].value.quote` | boolean | | |

**Settings.paymentRules**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "paymentRules" | Yes | |
| `[].value` | object \| null | Yes | The customer group's own payment rules, or null when it has none and inherits its nearest ancestor's. Send null through PATCH to drop an override and inherit again. At most 5 rules per method. |
| `[].value.payment_by_invoice` | object[] | | Items: max 5. |
| `[].value.payment_by_invoice[].conditions` | object | Yes | Conditions the rule narrows itself by, keyed by what each one matches on so a rule cannot carry two of the same. All present conditions must match. A rule with no conditions applies to every order. Money bounds are in the currency of the price list the cart is priced in. |
| `[].value.payment_by_invoice[].conditions.order_total` | object | | The net order total must fall within these bounds |
| `[].value.payment_by_invoice[].conditions.order_total.minimum` | number (double) \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_by_invoice[].conditions.order_total.maximum` | number (double) \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_by_invoice[].conditions.order_quantity` | object | | The size of the order must fall within these bounds |
| `[].value.payment_by_invoice[].conditions.order_quantity.type` | "total_quantity" \| "line_items" | Yes | What is counted: `total_quantity` sums the units across every line, `line_items` counts the lines themselves. |
| `[].value.payment_by_invoice[].conditions.order_quantity.minimum` | integer \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_by_invoice[].conditions.order_quantity.maximum` | integer \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_by_invoice[].conditions.available_credit` | object | | The credit the customer has left to spend must fall within these bounds. This is credit remaining, not the total credit limit. A customer with no credit limit set has unlimited credit and satisfies any minimum. |
| `[].value.payment_by_invoice[].conditions.available_credit.minimum` | number (double) \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_by_invoice[].conditions.available_credit.maximum` | number (double) \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_by_invoice[].conditions.products` | object | | Matches when a product in the cart satisfies any one of the filters. Filters are OR'd, and may mix SKU and metadata. |
| `[].value.payment_by_invoice[].conditions.products.filters` | (PaymentRule.Products.Sku \| PaymentRule.Products.Metadata)[] | Yes | Items: min 1, max 25. |
| `[].value.payment_by_invoice[].conditions.products.filters[].type` | "sku" | | |
| `[].value.payment_by_invoice[].conditions.products.filters[].value` | string | | Length: min 1. |
| `[].value.payment_by_invoice[].conditions.products.filters[].metadata_namespace` | string | | Length: min 1, max 256. |
| `[].value.payment_by_invoice[].conditions.products.filters[].metadata_key` | string | | Length: min 1, max 128. |
| `[].value.payment_by_invoice[].outcome` | PaymentRule.Outcome.Surcharge \| PaymentRule.Outcome.Discount \| PaymentRule.Outcome.Hide | Yes | What happens to the payment method when every condition matches |
| `[].value.payment_on_account` | object[] | | Items: max 5. |
| `[].value.payment_on_account[].conditions` | object | Yes | Conditions the rule narrows itself by, keyed by what each one matches on so a rule cannot carry two of the same. All present conditions must match. A rule with no conditions applies to every order. Money bounds are in the currency of the price list the cart is priced in. |
| `[].value.payment_on_account[].conditions.order_total` | object | | The net order total must fall within these bounds |
| `[].value.payment_on_account[].conditions.order_total.minimum` | number (double) \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_on_account[].conditions.order_total.maximum` | number (double) \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_on_account[].conditions.order_quantity` | object | | The size of the order must fall within these bounds |
| `[].value.payment_on_account[].conditions.order_quantity.type` | "total_quantity" \| "line_items" | Yes | What is counted: `total_quantity` sums the units across every line, `line_items` counts the lines themselves. |
| `[].value.payment_on_account[].conditions.order_quantity.minimum` | integer \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_on_account[].conditions.order_quantity.maximum` | integer \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_on_account[].conditions.available_credit` | object | | The credit the customer has left to spend must fall within these bounds. This is credit remaining, not the total credit limit. A customer with no credit limit set has unlimited credit and satisfies any minimum. |
| `[].value.payment_on_account[].conditions.available_credit.minimum` | number (double) \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_on_account[].conditions.available_credit.maximum` | number (double) \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.payment_on_account[].conditions.products` | object | | Matches when a product in the cart satisfies any one of the filters. Filters are OR'd, and may mix SKU and metadata. |
| `[].value.payment_on_account[].conditions.products.filters` | (PaymentRule.Products.Sku \| PaymentRule.Products.Metadata)[] | Yes | Items: min 1, max 25. |
| `[].value.payment_on_account[].conditions.products.filters[].type` | "sku" | | |
| `[].value.payment_on_account[].conditions.products.filters[].value` | string | | Length: min 1. |
| `[].value.payment_on_account[].conditions.products.filters[].metadata_namespace` | string | | Length: min 1, max 256. |
| `[].value.payment_on_account[].conditions.products.filters[].metadata_key` | string | | Length: min 1, max 128. |
| `[].value.payment_on_account[].outcome` | PaymentRule.Outcome.Surcharge \| PaymentRule.Outcome.Discount \| PaymentRule.Outcome.Hide | Yes | What happens to the payment method when every condition matches |
| `[].value.upfront_payment` | object[] | | Items: max 5. |
| `[].value.upfront_payment[].conditions` | object | Yes | Conditions the rule narrows itself by, keyed by what each one matches on so a rule cannot carry two of the same. All present conditions must match. A rule with no conditions applies to every order. Money bounds are in the currency of the price list the cart is priced in. |
| `[].value.upfront_payment[].conditions.order_total` | object | | The net order total must fall within these bounds |
| `[].value.upfront_payment[].conditions.order_total.minimum` | number (double) \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.upfront_payment[].conditions.order_total.maximum` | number (double) \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.upfront_payment[].conditions.order_quantity` | object | | The size of the order must fall within these bounds |
| `[].value.upfront_payment[].conditions.order_quantity.type` | "total_quantity" \| "line_items" | Yes | What is counted: `total_quantity` sums the units across every line, `line_items` counts the lines themselves. |
| `[].value.upfront_payment[].conditions.order_quantity.minimum` | integer \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.upfront_payment[].conditions.order_quantity.maximum` | integer \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.upfront_payment[].conditions.available_credit` | object | | The credit the customer has left to spend must fall within these bounds. This is credit remaining, not the total credit limit. A customer with no credit limit set has unlimited credit and satisfies any minimum. |
| `[].value.upfront_payment[].conditions.available_credit.minimum` | number (double) \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.upfront_payment[].conditions.available_credit.maximum` | number (double) \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.upfront_payment[].conditions.products` | object | | Matches when a product in the cart satisfies any one of the filters. Filters are OR'd, and may mix SKU and metadata. |
| `[].value.upfront_payment[].conditions.products.filters` | (PaymentRule.Products.Sku \| PaymentRule.Products.Metadata)[] | Yes | Items: min 1, max 25. |
| `[].value.upfront_payment[].conditions.products.filters[].type` | "sku" | | |
| `[].value.upfront_payment[].conditions.products.filters[].value` | string | | Length: min 1. |
| `[].value.upfront_payment[].conditions.products.filters[].metadata_namespace` | string | | Length: min 1, max 256. |
| `[].value.upfront_payment[].conditions.products.filters[].metadata_key` | string | | Length: min 1, max 128. |
| `[].value.upfront_payment[].outcome` | PaymentRule.Outcome.Surcharge \| PaymentRule.Outcome.Discount \| PaymentRule.Outcome.Hide | Yes | What happens to the payment method when every condition matches |
| `[].value.quote` | object[] | | Rules for the legacy request-for-quote payment method. The newer quoting system is a purchase type rather than a payment method, so it carries no rules. Items: max 5. |
| `[].value.quote[].conditions` | object | Yes | Conditions the rule narrows itself by, keyed by what each one matches on so a rule cannot carry two of the same. All present conditions must match. A rule with no conditions applies to every order. Money bounds are in the currency of the price list the cart is priced in. |
| `[].value.quote[].conditions.order_total` | object | | The net order total must fall within these bounds |
| `[].value.quote[].conditions.order_total.minimum` | number (double) \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.quote[].conditions.order_total.maximum` | number (double) \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.quote[].conditions.order_quantity` | object | | The size of the order must fall within these bounds |
| `[].value.quote[].conditions.order_quantity.type` | "total_quantity" \| "line_items" | Yes | What is counted: `total_quantity` sums the units across every line, `line_items` counts the lines themselves. |
| `[].value.quote[].conditions.order_quantity.minimum` | integer \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.quote[].conditions.order_quantity.maximum` | integer \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.quote[].conditions.available_credit` | object | | The credit the customer has left to spend must fall within these bounds. This is credit remaining, not the total credit limit. A customer with no credit limit set has unlimited credit and satisfies any minimum. |
| `[].value.quote[].conditions.available_credit.minimum` | number (double) \| null | | Inclusive lower bound. Absent or null is unbounded. Min 0. |
| `[].value.quote[].conditions.available_credit.maximum` | number (double) \| null | | Exclusive upper bound. Absent or null is unbounded. Min 0. |
| `[].value.quote[].conditions.products` | object | | Matches when a product in the cart satisfies any one of the filters. Filters are OR'd, and may mix SKU and metadata. |
| `[].value.quote[].conditions.products.filters` | (PaymentRule.Products.Sku \| PaymentRule.Products.Metadata)[] | Yes | Items: min 1, max 25. |
| `[].value.quote[].conditions.products.filters[].type` | "sku" | | |
| `[].value.quote[].conditions.products.filters[].value` | string | | Length: min 1. |
| `[].value.quote[].conditions.products.filters[].metadata_namespace` | string | | Length: min 1, max 256. |
| `[].value.quote[].conditions.products.filters[].metadata_key` | string | | Length: min 1, max 128. |
| `[].value.quote[].outcome` | PaymentRule.Outcome.Surcharge \| PaymentRule.Outcome.Discount \| PaymentRule.Outcome.Hide | Yes | What happens to the payment method when every condition matches |

**Settings.allowAddressEditing**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "allowAddressEditing" | Yes | |
| `[].value` | boolean \| null | Yes | |

**Settings.allowDefaultBillingModification**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "allowDefaultBillingModification" | Yes | |
| `[].value` | boolean \| null | Yes | |

**Settings.paymentOnAccountEnforceCreditLimit**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "paymentOnAccountEnforceCreditLimit" | Yes | |
| `[].value` | boolean \| null | Yes | |

**Settings.useMultiLocationStock**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "useMultiLocationStock" | Yes | |
| `[].value` | boolean \| null | Yes | |

**Settings.multiLocationStockConfig**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "multiLocationStockConfig" | Yes | |
| `[].value` | object \| null | Yes | |
| `[].value.useDefault` | boolean | | |
| `[].value.allowedStockLocationIds` | (string (uuid))[] | | |

**Settings.stockDisplay**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "stockDisplay" | Yes | |
| `[].value` | object \| null | Yes | |
| `[].value.show_status` | boolean | | |
| `[].value.show_units` | boolean | | |
| `[].value.max` | integer | | |
| `[].value.low` | integer | | |
| `[].value.last` | integer | | |

**Settings.quotingEngine**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "quotingEngine" | Yes | |
| `[].value` | object \| null | Yes | |
| `[].value.customer_create_quote` | boolean | | |

**Settings.allowCheckout**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "allowCheckout" | Yes | |
| `[].value` | boolean \| null | Yes | |

**Settings.recurringOrdersEngine**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "recurringOrdersEngine" | Yes | |
| `[].value` | object \| null | Yes | |
| `[].value.customer_create_recurring_orders` | boolean | | |

```json
[
  {
    "key": "orderTotalsValidation",
    "value": [
      {
        "currency_code": "gbp",
        "minimum_value": 0,
        "maximum_value": 0,
        "compare_type": "gross"
      }
    ]
  }
]
```

### Responses

#### 204: The settings were updated. No body.

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Ordering API

URL: https://docs.sparklayer.io/developers/api/ordering

Create, update, calculate and complete carts with the Ordering API to place orders for customers, check their pricing first and handle validation errors.

The Ordering API lets you create SparkLayer carts on behalf of your customers and complete them as orders on your connected eCommerce platform — for example to place orders from an external system or for drop shipping. Carts use the same pricing, validation, ordering rules and checkout logic as the SparkLayer cart your customers use, except that upfront payment methods aren't available for carts created through the API.

> **Beta**
>
> The Ordering API is in beta. If you'd like to use it, email [support@sparklayer.io](mailto:support@sparklayer.io) and our team will help you get started.

The API reference below gives full endpoint and schema details. This guide covers checking customer-specific pricing, the cart and order lifecycle, and how validation works.

## Customer-specific pricing lookup

The [Get customer-specific pricing](https://docs.sparklayer.io/developers/api/core/get-customer-specific-pricing.md) endpoint is part of the Core API. Use it before creating a cart to check pricing and price breaks for validation or user feedback.

It calculates real-time pricing for one or more SKUs in the context of a specific customer. It returns per-line-item unit prices, line totals, and quantity price breaks, accounting for the customer's assigned price lists and any customer-level discount percentage.

### Price calculation

SparkLayer looks up the customer's assigned price lists and uses those to calculate accurate pricing for each requested product. This includes:

- **Quantity price breaks** — the price adjusts based on how many units are being ordered
- **Variant aggregation** — if your store is configured to apply price breaks across variants, quantities across sizes or colours of the same product are combined when determining the price tier. For example, ordering 5× size M and 5× size L could unlock the 10-unit price break for both.
- **Customer discounts** — any discount assigned to the customer is applied on top of the list price

Each product in the response includes the unit price, line total, and a full breakdown of available quantity price breaks. All prices are returned as net values.

### Potential issues

- **Partial pricing failure** — if any product can't be priced, the response status is `207`: affected line items include an error with null pricing data, and successfully priced items are returned alongside them.
- **Invalid request** — a `400` is returned if the request is malformed, the customer doesn't exist, or the customer has no price lists configured.

## Order lifecycle

Every order starts as a cart for a customer, and goes through four steps:

1. [Create a cart](#1-create-an-empty-cart) for the customer.
2. [Update the cart](#2-update-the-cart) with line items and order details, and review any validation errors.
3. [Calculate the cart](#3-calculate-the-cart) to get totals and the available shipping and payment methods. Calculate again with your chosen shipping rate to confirm the totals.
4. [Complete the cart](#4-complete-the-cart) with the shipping rate and payment method to place the order.

## 1. Create an empty cart

[Create a cart](https://docs.sparklayer.io/developers/api/ordering/create-cart.md) for the customer you're placing the order for. Identify the customer with `customer_id` and `customer_lookup_by`: `sparklayer` (the customer's SparkLayer ID), `platform` (the ID from your eCommerce platform) or `email`.

A new cart is empty. It holds all the order information, including line items, quantities and the shipping address. The response includes a `cart_id`: use it for every later request about the cart.

## 2. Update the cart

[Update the cart](https://docs.sparklayer.io/developers/api/ordering/update-cart.md) with the information the order needs:

- Line items and their quantities
- The shipping address (`shipping_address_id`), or a `temporary_shipping_address`
- The customer reference, PO number, requested shipping date and custom fields

Each update replaces the cart's line items, so always send the full list with the final quantity of each item. Omitting `line_items`, or sending an empty array, empties the cart.

For drop shipping, use a temporary shipping address when the delivery address shouldn't be stored against the customer's account.

### Validation

Each cart update returns the latest cart state, including any validation errors generated by your business rules in SparkLayer, such as:

- Minimum or maximum order quantity restrictions
- Product availability constraints
- Customer-specific purchasing restrictions

The response also has a result for each line item, so you can see how each requested item was processed and whether it was adjusted or has a validation error.

The [Update a cart](https://docs.sparklayer.io/developers/api/ordering/update-cart.md) and [Calculate a cart](https://docs.sparklayer.io/developers/api/ordering/calculate-cart.md) operations don't fail because of validation errors: the errors are included in the response for your application to handle. Calculating does return a `422` if the cart is empty or the shipping rate you chose isn't available — see [Cart errors](https://docs.sparklayer.io/developers/errors.md#cart-errors).

The [Complete a cart](https://docs.sparklayer.io/developers/api/ordering/complete-cart.md) operation behaves differently. If validation errors exist, it returns a `422` and the cart isn't completed. To allow specific validation errors, list them in the `ignore_validation_errors` property.

## 3. Calculate the cart

[Calculate the cart](https://docs.sparklayer.io/developers/api/ordering/calculate-cart.md) before completing it. SparkLayer:

- Calculates the order totals and tax with the connected platform
- Applies pricing
- Returns the available shipping methods and their costs
- Returns the allowed payment methods
- Validates the current cart state

To choose a shipping method, pass its `shipping_rate_handle`. If you leave it out, SparkLayer uses the first available shipping rate. Calculate again after changing the shipping rate or the cart, so the totals you show are up to date. 

## 4. Complete the cart

[Complete the cart](https://docs.sparklayer.io/developers/api/ordering/complete-cart.md) once it's valid and you've chosen how to ship and pay. Send:

- `shipping_rate_handle`: a shipping rate returned when you calculated the cart
- `payment_method`: `paymentByInvoice` or `paymentOnAccount`
- `ignore_validation_errors`: the validation errors to allow (an empty list allows none, `"*"` allows all)

Completing a cart turns it into a SparkLayer order and submits it to the connected eCommerce platform.

The response includes the new `purchase_id`. The cart is deleted once it's completed, so later requests with its ID return `404`.

## Endpoints

- [POST Create a cart](https://docs.sparklayer.io/developers/api/ordering/create-cart.md)
- [GET Get a cart](https://docs.sparklayer.io/developers/api/ordering/get-cart.md)
- [PATCH Update a cart](https://docs.sparklayer.io/developers/api/ordering/update-cart.md)
- [DELETE Delete a cart](https://docs.sparklayer.io/developers/api/ordering/delete-cart.md)
- [POST Complete a cart](https://docs.sparklayer.io/developers/api/ordering/complete-cart.md)
- [POST Calculate a cart](https://docs.sparklayer.io/developers/api/ordering/calculate-cart.md)

## Next steps

- [Authentication](https://docs.sparklayer.io/developers/authentication.md): get an access token for your requests.
- [Errors](https://docs.sparklayer.io/developers/errors.md#cart-errors): the cart error codes and what they mean.
- [Purchasing API](https://docs.sparklayer.io/developers/api/purchasing.md): the orders and quotes customers see in My Account.


---

# Create a cart

URL: https://docs.sparklayer.io/developers/api/ordering/create-cart
Operation: `POST /api/v1/carts` (operationId `createCart`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ordering.yaml

Creates an empty cart for a customer and returns its `cart_id` with a `201`. Identify the customer with `customer_id` and `customer_lookup_by`: `sparklayer` (the customer's UUID), `platform` (the ID from your eCommerce platform) or `email`. An unknown customer returns `400` (`resource-id-not-found`), and the `Accept-Language` header sets the cart's locale (default `en-US`).

`POST /api/v1/carts`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/carts" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "<customer_id>",
  "customer_lookup_by": "sparklayer"
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `customer_id` | string | | The customer the cart is for, identified as set by `customer_lookup_by`. |
| `customer_lookup_by` | "sparklayer" \| "platform" \| "email" | | What `customer_id` is: `sparklayer` (the customer's UUID), `platform` (the ID from your eCommerce platform) or `email`. |

```json
{
  "customer_id": "<customer_id>",
  "customer_lookup_by": "sparklayer"
}
```

### Responses

#### 201: The cart was created. Use its `cart_id` in every later request about the cart.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `cart_id` | string (uuid) | | |

```json
{
  "cart_id": "9151f21f-43ae-43b4-92f3-f4af67cdf544"
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Get a cart

URL: https://docs.sparklayer.io/developers/api/ordering/get-cart
Operation: `GET /api/v1/carts/{id}` (operationId `getCart`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ordering.yaml

Returns the cart's line items, addresses, totals and any `validation_errors` (such as minimum order or stock rules) that you need to resolve or ignore before completing it. Returns `404` if the cart doesn't exist, for example because it has already been completed.

`GET /api/v1/carts/{id}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/carts/9151f21f-43ae-43b4-92f3-f4af67cdf544" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The cart's ID: the `cart_id` returned by **Create a cart**. Example: `9151f21f-43ae-43b4-92f3-f4af67cdf544` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: The cart, including its line items, totals and any `validation_errors`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | | |
| `intent` | "ORDER" \| "QUOTE" | | |
| `customer_id` | string (uuid) | | |
| `shipping_address_id` | string (uuid) \| null | | |
| `billing_address_id` | string (uuid) \| null | | |
| `items` | object[] | | |
| `items[].sku` | string | | |
| `items[].quantity` | integer | | |
| `items[].line_total` | object | | |
| `items[].line_total.net` | string | | |
| `items[].line_total.gross` | string | | |
| `items[].line_total.tax_rate` | number (float) \| null | | |
| `items[].line_total.currency_code` | string | | |
| `items[].line_total.tax_inclusive_display` | boolean | | Whether the storefront should show the gross amount and label it tax inclusive. Not derivable from tax_rate, since a zero-rated SKU on a tax-inclusive price list has a rate of 0 but must still be labelled. Display only - it says nothing about what is charged. Default: `false`. |
| `items[].unit_total` | object \| null | | |
| `items[].unit_total.net` | string | | |
| `items[].unit_total.gross` | string | | |
| `items[].unit_total.tax_rate` | number (float) \| null | | |
| `items[].unit_total.currency_code` | string | | |
| `items[].unit_total.tax_inclusive_display` | boolean | | Whether the storefront should show the gross amount and label it tax inclusive. Not derivable from tax_rate, since a zero-rated SKU on a tax-inclusive price list has a rate of 0 but must still be labelled. Display only - it says nothing about what is charged. Default: `false`. |
| `totals` | object | | |
| `totals.total` | object | | |
| `totals.total.pre_discount` | object | | |
| `totals.total.pre_discount.net` | object | | |
| `totals.total.pre_discount.net.amount` | string | | |
| `totals.total.pre_discount.net.currency_code` | string | | |
| `totals.total.pre_discount.gross` | object | | |
| `totals.total.pre_discount.gross.amount` | string | | |
| `totals.total.pre_discount.gross.currency_code` | string | | |
| `totals.total.pre_discount.tax` | object | | |
| `totals.total.pre_discount.tax.amount` | string | | |
| `totals.total.pre_discount.tax.currency_code` | string | | |
| `totals.total.pre_discount.apportioned_tax_rate` | number (float) | | |
| `totals.total.pre_discount.currency` | string | | |
| `totals.total.discount` | object \| null | | |
| `totals.total.discount.net` | object | | |
| `totals.total.discount.net.amount` | string | | |
| `totals.total.discount.net.currency_code` | string | | |
| `totals.total.discount.gross` | object | | |
| `totals.total.discount.gross.amount` | string | | |
| `totals.total.discount.gross.currency_code` | string | | |
| `totals.total.discount.tax` | object | | |
| `totals.total.discount.tax.amount` | string | | |
| `totals.total.discount.tax.currency_code` | string | | |
| `totals.total.discount.apportioned_tax_rate` | number (float) | | |
| `totals.total.discount.currency` | string | | |
| `totals.total.charge` | object | | |
| `totals.total.charge.net` | object | | |
| `totals.total.charge.net.amount` | string | | |
| `totals.total.charge.net.currency_code` | string | | |
| `totals.total.charge.gross` | object | | |
| `totals.total.charge.gross.amount` | string | | |
| `totals.total.charge.gross.currency_code` | string | | |
| `totals.total.charge.tax` | object | | |
| `totals.total.charge.tax.amount` | string | | |
| `totals.total.charge.tax.currency_code` | string | | |
| `totals.total.charge.apportioned_tax_rate` | number (float) | | |
| `totals.total.charge.currency` | string | | |
| `totals.shipping` | object | | |
| `totals.shipping.pre_discount` | object | | |
| `totals.shipping.pre_discount.net` | object | | |
| `totals.shipping.pre_discount.net.amount` | string | | |
| `totals.shipping.pre_discount.net.currency_code` | string | | |
| `totals.shipping.pre_discount.gross` | object | | |
| `totals.shipping.pre_discount.gross.amount` | string | | |
| `totals.shipping.pre_discount.gross.currency_code` | string | | |
| `totals.shipping.pre_discount.tax` | object | | |
| `totals.shipping.pre_discount.tax.amount` | string | | |
| `totals.shipping.pre_discount.tax.currency_code` | string | | |
| `totals.shipping.pre_discount.apportioned_tax_rate` | number (float) | | |
| `totals.shipping.pre_discount.currency` | string | | |
| `totals.shipping.discount` | object \| null | | |
| `totals.shipping.discount.net` | object | | |
| `totals.shipping.discount.net.amount` | string | | |
| `totals.shipping.discount.net.currency_code` | string | | |
| `totals.shipping.discount.gross` | object | | |
| `totals.shipping.discount.gross.amount` | string | | |
| `totals.shipping.discount.gross.currency_code` | string | | |
| `totals.shipping.discount.tax` | object | | |
| `totals.shipping.discount.tax.amount` | string | | |
| `totals.shipping.discount.tax.currency_code` | string | | |
| `totals.shipping.discount.apportioned_tax_rate` | number (float) | | |
| `totals.shipping.discount.currency` | string | | |
| `totals.shipping.charge` | object | | |
| `totals.shipping.charge.net` | object | | |
| `totals.shipping.charge.net.amount` | string | | |
| `totals.shipping.charge.net.currency_code` | string | | |
| `totals.shipping.charge.gross` | object | | |
| `totals.shipping.charge.gross.amount` | string | | |
| `totals.shipping.charge.gross.currency_code` | string | | |
| `totals.shipping.charge.tax` | object | | |
| `totals.shipping.charge.tax.amount` | string | | |
| `totals.shipping.charge.tax.currency_code` | string | | |
| `totals.shipping.charge.apportioned_tax_rate` | number (float) | | |
| `totals.shipping.charge.currency` | string | | |
| `totals.sub_total` | object | | |
| `totals.sub_total.pre_discount` | object | | |
| `totals.sub_total.pre_discount.net` | object | | |
| `totals.sub_total.pre_discount.net.amount` | string | | |
| `totals.sub_total.pre_discount.net.currency_code` | string | | |
| `totals.sub_total.pre_discount.gross` | object | | |
| `totals.sub_total.pre_discount.gross.amount` | string | | |
| `totals.sub_total.pre_discount.gross.currency_code` | string | | |
| `totals.sub_total.pre_discount.tax` | object | | |
| `totals.sub_total.pre_discount.tax.amount` | string | | |
| `totals.sub_total.pre_discount.tax.currency_code` | string | | |
| `totals.sub_total.pre_discount.apportioned_tax_rate` | number (float) | | |
| `totals.sub_total.pre_discount.currency` | string | | |
| `totals.sub_total.discount` | object \| null | | |
| `totals.sub_total.discount.net` | object | | |
| `totals.sub_total.discount.net.amount` | string | | |
| `totals.sub_total.discount.net.currency_code` | string | | |
| `totals.sub_total.discount.gross` | object | | |
| `totals.sub_total.discount.gross.amount` | string | | |
| `totals.sub_total.discount.gross.currency_code` | string | | |
| `totals.sub_total.discount.tax` | object | | |
| `totals.sub_total.discount.tax.amount` | string | | |
| `totals.sub_total.discount.tax.currency_code` | string | | |
| `totals.sub_total.discount.apportioned_tax_rate` | number (float) | | |
| `totals.sub_total.discount.currency` | string | | |
| `totals.sub_total.charge` | object | | |
| `totals.sub_total.charge.net` | object | | |
| `totals.sub_total.charge.net.amount` | string | | |
| `totals.sub_total.charge.net.currency_code` | string | | |
| `totals.sub_total.charge.gross` | object | | |
| `totals.sub_total.charge.gross.amount` | string | | |
| `totals.sub_total.charge.gross.currency_code` | string | | |
| `totals.sub_total.charge.tax` | object | | |
| `totals.sub_total.charge.tax.amount` | string | | |
| `totals.sub_total.charge.tax.currency_code` | string | | |
| `totals.sub_total.charge.apportioned_tax_rate` | number (float) | | |
| `totals.sub_total.charge.currency` | string | | |
| `customer_addresses` | object[] | | |
| `customer_addresses[].id` | string | | |
| `customer_addresses[].uuid` | string | | |
| `customer_addresses[].first_name` | string | | |
| `customer_addresses[].last_name` | string | | |
| `customer_addresses[].company` | string | | |
| `customer_addresses[].description` | string | | |
| `customer_addresses[].address_line_1` | string | | |
| `customer_addresses[].address_line_2` | string | | |
| `customer_addresses[].city` | string | | |
| `customer_addresses[].postal_code` | string \| null | | |
| `customer_addresses[].country_code` | string | | |
| `customer_addresses[].region_code` | string \| null | | |
| `customer_addresses[].phone` | string | | |
| `customer_addresses[].external_id` | string \| null | | |
| `shipping_rate_handle` | string \| null | | |
| `payment_method` | string \| null | | |
| `validation_errors` | (CartValidationErrorMaximumOrderItemQuantity \| CartValidationErrorMaximumOrderTotals \| CartValidationErrorMaximumParentQuantity \| CartValidationErrorMaximumVariantQuantity \| CartValidationErrorMinimumOrderItemQuantity \| CartValidationErrorMinimumOrderTotals \| CartValidationErrorMinimumParentQuantity \| CartValidationErrorMinimumVariantQuantity \| CartValidationErrorPackSize \| CartValidationErrorPricingUnavailable \| CartValidationErrorPricingUnavailableForSelectedQty \| CartValidationErrorQuantityUnavailable)[] | | |
| `validation_errors[].type` | "maximum-order-item-quantity" | | |
| `validation_errors[].overridden` | boolean | | |
| `validation_errors[].maximum` | integer | | |
| `validation_errors[].amount` | number (float) | | |
| `validation_errors[].parent_sku` | string | | |
| `validation_errors[].product_name` | string | | |
| `validation_errors[].minimum` | integer | | |
| `validation_errors[].pack_size` | integer | | |
| `validation_errors[].variant_sku` | string | | |
| `validation_errors[].available_quantity` | integer | | |
| `customer_reference` | string \| null | | |
| `po_number` | string \| null | | |
| `shipping_requested_date` | string \| null | | |
| `custom_fields` | object[] | | The cart's current custom fields. |
| `custom_fields[].name` | string | Yes | |
| `custom_fields[].value` | string | Yes | |

```json
{
  "id": "3f2b8c1e-5d4a-4e6f-9b7c-1a2d3e4f5a6b",
  "intent": "ORDER",
  "customer_id": "3f2b8c1e-5d4a-4e6f-9b7c-1a2d3e4f5a6b",
  "shipping_address_id": "3f2b8c1e-5d4a-4e6f-9b7c-1a2d3e4f5a6b",
  "billing_address_id": "3f2b8c1e-5d4a-4e6f-9b7c-1a2d3e4f5a6b",
  "items": [
    {
      "sku": "<sku>",
      "quantity": 0,
      "line_total": {
        "net": "<net>",
        "gross": "<gross>",
        "tax_rate": 0,
        "currency_code": "<currency_code>",
        "tax_inclusive_display": false
      },
      "unit_total": {
        "net": "<net>",
        "gross": "<gross>",
        "tax_rate": 0,
        "currency_code": "<currency_code>",
        "tax_inclusive_display": false
      }
    }
  ],
  "totals": {
    "total": {
      "pre_discount": {
        "net": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "gross": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "tax": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "apportioned_tax_rate": 0,
        "currency": "<currency>"
      },
      "discount": {
        "net": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "gross": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "tax": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "apportioned_tax_rate": 0,
        "currency": "<currency>"
      },
      "charge": {
        "net": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "gross": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "tax": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "apportioned_tax_rate": 0,
        "currency": "<currency>"
      }
    },
    "shipping": {
      "pre_discount": {
        "net": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "gross": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "tax": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "apportioned_tax_rate": 0,
        "currency": "<currency>"
      },
      "discount": {
        "net": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "gross": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "tax": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "apportioned_tax_rate": 0,
        "currency": "<currency>"
      },
      "charge": {
        "net": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "gross": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "tax": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "apportioned_tax_rate": 0,
        "currency": "<currency>"
      }
    },
    "sub_total": {
      "pre_discount": {
        "net": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "gross": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "tax": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "apportioned_tax_rate": 0,
        "currency": "<currency>"
      },
      "discount": {
        "net": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "gross": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "tax": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "apportioned_tax_rate": 0,
        "currency": "<currency>"
      },
      "charge": {
        "net": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "gross": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "tax": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "apportioned_tax_rate": 0,
        "currency": "<currency>"
      }
    }
  },
  "customer_addresses": [
    {
      "id": "<id>",
      "uuid": "<uuid>",
      "first_name": "<first_name>",
      "last_name": "<last_name>",
      "company": "<company>",
      "description": "<description>",
      "address_line_1": "<address_line_1>",
      "address_line_2": "<address_line_2>",
      "city": "<city>",
      "postal_code": "<postal_code>",
      "country_code": "<country_code>",
      "region_code": "<region_code>",
      "phone": "<phone>",
      "external_id": "<external_id>"
    }
  ],
  "shipping_rate_handle": "<shipping_rate_handle>",
  "payment_method": "<payment_method>",
  "validation_errors": [
    {
      "type": "maximum-order-item-quantity",
      "overridden": true,
      "maximum": 0
    }
  ],
  "customer_reference": "<customer_reference>",
  "po_number": "<po_number>",
  "shipping_requested_date": "<shipping_requested_date>",
  "custom_fields": [
    {
      "name": "<name>",
      "value": "<value>"
    }
  ]
}
```

#### 404: Cart not found

#### 422: Unprocessable Entity

One of these:

**CartErrorResponse**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | 422 | | HTTP Status code returned from API |
| `title` | "cart-error" | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | "cart-shipping-rate-handle-unavailable" \| "cart-customer-not-found" \| "cart-impersonator-user-not-found" \| "cart-payment-method-unavailable" | | Machine-readable error code |

- **Error**: the standard error body (below).

```json
{
  "detail": "Cart error occurred",
  "status": 422,
  "title": "cart-error",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "cart-shipping-rate-handle-unavailable"
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Delete a cart

URL: https://docs.sparklayer.io/developers/api/ordering/delete-cart
Operation: `DELETE /api/v1/carts/{id}` (operationId `deleteCart`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ordering.yaml

Deletes a cart and returns `204`. The request succeeds even if the cart doesn't exist, so it's safe to retry.

`DELETE /api/v1/carts/{id}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X DELETE "https://app.sparklayer.io/api/v1/carts/9151f21f-43ae-43b4-92f3-f4af67cdf544" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The cart's ID: the `cart_id` returned by **Create a cart**. Example: `9151f21f-43ae-43b4-92f3-f4af67cdf544` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 204: The cart was deleted, or didn't exist. No body.

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Update a cart

URL: https://docs.sparklayer.io/developers/api/ordering/update-cart
Operation: `PATCH /api/v1/carts/{id}` (operationId `updateCart`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ordering.yaml

Updates the cart and returns it along with a result for each line item. Line items are always replaced: quantities are absolute, and omitting `line_items` or sending an empty array empties the cart. `custom_fields` also replaces the existing set, `temporary_shipping_address` takes precedence over `shipping_address_id`, and an empty string clears `customer_reference`, `po_number` or `shipping_requested_date`.

`PATCH /api/v1/carts/{id}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PATCH "https://app.sparklayer.io/api/v1/carts/9151f21f-43ae-43b4-92f3-f4af67cdf544" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "line_items": [
    {
      "sku": "<sku>",
      "quantity": 0
    }
  ],
  "shipping_address_id": "<shipping_address_id>",
  "temporary_shipping_address": {
    "first_name": "<first_name>",
    "last_name": "<last_name>",
    "company": "<company>",
    "address_line1": "<address_line1>",
    "address_line2": "<address_line2>",
    "city": "<city>",
    "region_code": "<region_code>",
    "postal_code": "<postal_code>",
    "country_code": "<country_code>",
    "phone": "<phone>"
  },
  "customer_reference": "<customer_reference>",
  "po_number": "<po_number>",
  "shipping_requested_date": "<shipping_requested_date>",
  "custom_fields": [
    {
      "name": "<name>",
      "value": "<value>"
    }
  ]
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The cart's ID: the `cart_id` returned by **Create a cart**. Example: `9151f21f-43ae-43b4-92f3-f4af67cdf544` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `line_items` | object[] | | Replaces all existing cart line items. The provided quantities are absolute values (not deltas). Passing an empty array clears the cart. |
| `line_items[].sku` | string | | |
| `line_items[].quantity` | integer | | |
| `shipping_address_id` | string \| null | | |
| `temporary_shipping_address` | object \| null | | |
| `temporary_shipping_address.first_name` | string \| null | | |
| `temporary_shipping_address.last_name` | string \| null | | |
| `temporary_shipping_address.company` | string \| null | | |
| `temporary_shipping_address.address_line1` | string | | |
| `temporary_shipping_address.address_line2` | string \| null | | |
| `temporary_shipping_address.city` | string | | |
| `temporary_shipping_address.region_code` | string \| null | | |
| `temporary_shipping_address.postal_code` | string | | |
| `temporary_shipping_address.country_code` | string | | |
| `temporary_shipping_address.phone` | string \| null | | |
| `customer_reference` | string \| null | | |
| `po_number` | string \| null | | |
| `shipping_requested_date` | string \| null | | |
| `custom_fields` | object[] | | Replaces all existing custom fields on the cart. Any existing field not included is removed. Passing an empty array clears all custom fields. |
| `custom_fields[].name` | string | Yes | |
| `custom_fields[].value` | string \| null | | A null value has the same effect as omitting this field from the array: it is not included in the replaced set of custom fields. |

```json
{
  "line_items": [
    {
      "sku": "<sku>",
      "quantity": 0
    }
  ],
  "shipping_address_id": "<shipping_address_id>",
  "temporary_shipping_address": {
    "first_name": "<first_name>",
    "last_name": "<last_name>",
    "company": "<company>",
    "address_line1": "<address_line1>",
    "address_line2": "<address_line2>",
    "city": "<city>",
    "region_code": "<region_code>",
    "postal_code": "<postal_code>",
    "country_code": "<country_code>",
    "phone": "<phone>"
  },
  "customer_reference": "<customer_reference>",
  "po_number": "<po_number>",
  "shipping_requested_date": "<shipping_requested_date>",
  "custom_fields": [
    {
      "name": "<name>",
      "value": "<value>"
    }
  ]
}
```

### Responses

#### 200: The updated cart, with a result for each line item.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `cart` | object | | |
| `cart.id` | string (uuid) | | |
| `cart.intent` | "ORDER" \| "QUOTE" | | |
| `cart.customer_id` | string (uuid) | | |
| `cart.shipping_address_id` | string (uuid) \| null | | |
| `cart.billing_address_id` | string (uuid) \| null | | |
| `cart.items` | object[] | | |
| `cart.items[].sku` | string | | |
| `cart.items[].quantity` | integer | | |
| `cart.items[].line_total` | object | | |
| `cart.items[].line_total.net` | string | | |
| `cart.items[].line_total.gross` | string | | |
| `cart.items[].line_total.tax_rate` | number (float) \| null | | |
| `cart.items[].line_total.currency_code` | string | | |
| `cart.items[].line_total.tax_inclusive_display` | boolean | | Whether the storefront should show the gross amount and label it tax inclusive. Not derivable from tax_rate, since a zero-rated SKU on a tax-inclusive price list has a rate of 0 but must still be labelled. Display only - it says nothing about what is charged. Default: `false`. |
| `cart.items[].unit_total` | object \| null | | |
| `cart.items[].unit_total.net` | string | | |
| `cart.items[].unit_total.gross` | string | | |
| `cart.items[].unit_total.tax_rate` | number (float) \| null | | |
| `cart.items[].unit_total.currency_code` | string | | |
| `cart.items[].unit_total.tax_inclusive_display` | boolean | | Whether the storefront should show the gross amount and label it tax inclusive. Not derivable from tax_rate, since a zero-rated SKU on a tax-inclusive price list has a rate of 0 but must still be labelled. Display only - it says nothing about what is charged. Default: `false`. |
| `cart.totals` | object | | |
| `cart.totals.total` | object | | |
| `cart.totals.total.pre_discount` | object | | |
| `cart.totals.total.pre_discount.net` | object | | |
| `cart.totals.total.pre_discount.net.amount` | string | | |
| `cart.totals.total.pre_discount.net.currency_code` | string | | |
| `cart.totals.total.pre_discount.gross` | object | | |
| `cart.totals.total.pre_discount.gross.amount` | string | | |
| `cart.totals.total.pre_discount.gross.currency_code` | string | | |
| `cart.totals.total.pre_discount.tax` | object | | |
| `cart.totals.total.pre_discount.tax.amount` | string | | |
| `cart.totals.total.pre_discount.tax.currency_code` | string | | |
| `cart.totals.total.pre_discount.apportioned_tax_rate` | number (float) | | |
| `cart.totals.total.pre_discount.currency` | string | | |
| `cart.totals.total.discount` | object \| null | | |
| `cart.totals.total.discount.net` | object | | |
| `cart.totals.total.discount.net.amount` | string | | |
| `cart.totals.total.discount.net.currency_code` | string | | |
| `cart.totals.total.discount.gross` | object | | |
| `cart.totals.total.discount.gross.amount` | string | | |
| `cart.totals.total.discount.gross.currency_code` | string | | |
| `cart.totals.total.discount.tax` | object | | |
| `cart.totals.total.discount.tax.amount` | string | | |
| `cart.totals.total.discount.tax.currency_code` | string | | |
| `cart.totals.total.discount.apportioned_tax_rate` | number (float) | | |
| `cart.totals.total.discount.currency` | string | | |
| `cart.totals.total.charge` | object | | |
| `cart.totals.total.charge.net` | object | | |
| `cart.totals.total.charge.net.amount` | string | | |
| `cart.totals.total.charge.net.currency_code` | string | | |
| `cart.totals.total.charge.gross` | object | | |
| `cart.totals.total.charge.gross.amount` | string | | |
| `cart.totals.total.charge.gross.currency_code` | string | | |
| `cart.totals.total.charge.tax` | object | | |
| `cart.totals.total.charge.tax.amount` | string | | |
| `cart.totals.total.charge.tax.currency_code` | string | | |
| `cart.totals.total.charge.apportioned_tax_rate` | number (float) | | |
| `cart.totals.total.charge.currency` | string | | |
| `cart.totals.shipping` | object | | |
| `cart.totals.shipping.pre_discount` | object | | |
| `cart.totals.shipping.pre_discount.net` | object | | |
| `cart.totals.shipping.pre_discount.net.amount` | string | | |
| `cart.totals.shipping.pre_discount.net.currency_code` | string | | |
| `cart.totals.shipping.pre_discount.gross` | object | | |
| `cart.totals.shipping.pre_discount.gross.amount` | string | | |
| `cart.totals.shipping.pre_discount.gross.currency_code` | string | | |
| `cart.totals.shipping.pre_discount.tax` | object | | |
| `cart.totals.shipping.pre_discount.tax.amount` | string | | |
| `cart.totals.shipping.pre_discount.tax.currency_code` | string | | |
| `cart.totals.shipping.pre_discount.apportioned_tax_rate` | number (float) | | |
| `cart.totals.shipping.pre_discount.currency` | string | | |
| `cart.totals.shipping.discount` | object \| null | | |
| `cart.totals.shipping.discount.net` | object | | |
| `cart.totals.shipping.discount.net.amount` | string | | |
| `cart.totals.shipping.discount.net.currency_code` | string | | |
| `cart.totals.shipping.discount.gross` | object | | |
| `cart.totals.shipping.discount.gross.amount` | string | | |
| `cart.totals.shipping.discount.gross.currency_code` | string | | |
| `cart.totals.shipping.discount.tax` | object | | |
| `cart.totals.shipping.discount.tax.amount` | string | | |
| `cart.totals.shipping.discount.tax.currency_code` | string | | |
| `cart.totals.shipping.discount.apportioned_tax_rate` | number (float) | | |
| `cart.totals.shipping.discount.currency` | string | | |
| `cart.totals.shipping.charge` | object | | |
| `cart.totals.shipping.charge.net` | object | | |
| `cart.totals.shipping.charge.net.amount` | string | | |
| `cart.totals.shipping.charge.net.currency_code` | string | | |
| `cart.totals.shipping.charge.gross` | object | | |
| `cart.totals.shipping.charge.gross.amount` | string | | |
| `cart.totals.shipping.charge.gross.currency_code` | string | | |
| `cart.totals.shipping.charge.tax` | object | | |
| `cart.totals.shipping.charge.tax.amount` | string | | |
| `cart.totals.shipping.charge.tax.currency_code` | string | | |
| `cart.totals.shipping.charge.apportioned_tax_rate` | number (float) | | |
| `cart.totals.shipping.charge.currency` | string | | |
| `cart.totals.sub_total` | object | | |
| `cart.totals.sub_total.pre_discount` | object | | |
| `cart.totals.sub_total.pre_discount.net` | object | | |
| `cart.totals.sub_total.pre_discount.net.amount` | string | | |
| `cart.totals.sub_total.pre_discount.net.currency_code` | string | | |
| `cart.totals.sub_total.pre_discount.gross` | object | | |
| `cart.totals.sub_total.pre_discount.gross.amount` | string | | |
| `cart.totals.sub_total.pre_discount.gross.currency_code` | string | | |
| `cart.totals.sub_total.pre_discount.tax` | object | | |
| `cart.totals.sub_total.pre_discount.tax.amount` | string | | |
| `cart.totals.sub_total.pre_discount.tax.currency_code` | string | | |
| `cart.totals.sub_total.pre_discount.apportioned_tax_rate` | number (float) | | |
| `cart.totals.sub_total.pre_discount.currency` | string | | |
| `cart.totals.sub_total.discount` | object \| null | | |
| `cart.totals.sub_total.discount.net` | object | | |
| `cart.totals.sub_total.discount.net.amount` | string | | |
| `cart.totals.sub_total.discount.net.currency_code` | string | | |
| `cart.totals.sub_total.discount.gross` | object | | |
| `cart.totals.sub_total.discount.gross.amount` | string | | |
| `cart.totals.sub_total.discount.gross.currency_code` | string | | |
| `cart.totals.sub_total.discount.tax` | object | | |
| `cart.totals.sub_total.discount.tax.amount` | string | | |
| `cart.totals.sub_total.discount.tax.currency_code` | string | | |
| `cart.totals.sub_total.discount.apportioned_tax_rate` | number (float) | | |
| `cart.totals.sub_total.discount.currency` | string | | |
| `cart.totals.sub_total.charge` | object | | |
| `cart.totals.sub_total.charge.net` | object | | |
| `cart.totals.sub_total.charge.net.amount` | string | | |
| `cart.totals.sub_total.charge.net.currency_code` | string | | |
| `cart.totals.sub_total.charge.gross` | object | | |
| `cart.totals.sub_total.charge.gross.amount` | string | | |
| `cart.totals.sub_total.charge.gross.currency_code` | string | | |
| `cart.totals.sub_total.charge.tax` | object | | |
| `cart.totals.sub_total.charge.tax.amount` | string | | |
| `cart.totals.sub_total.charge.tax.currency_code` | string | | |
| `cart.totals.sub_total.charge.apportioned_tax_rate` | number (float) | | |
| `cart.totals.sub_total.charge.currency` | string | | |
| `cart.customer_addresses` | object[] | | |
| `cart.customer_addresses[].id` | string | | |
| `cart.customer_addresses[].uuid` | string | | |
| `cart.customer_addresses[].first_name` | string | | |
| `cart.customer_addresses[].last_name` | string | | |
| `cart.customer_addresses[].company` | string | | |
| `cart.customer_addresses[].description` | string | | |
| `cart.customer_addresses[].address_line_1` | string | | |
| `cart.customer_addresses[].address_line_2` | string | | |
| `cart.customer_addresses[].city` | string | | |
| `cart.customer_addresses[].postal_code` | string \| null | | |
| `cart.customer_addresses[].country_code` | string | | |
| `cart.customer_addresses[].region_code` | string \| null | | |
| `cart.customer_addresses[].phone` | string | | |
| `cart.customer_addresses[].external_id` | string \| null | | |
| `cart.shipping_rate_handle` | string \| null | | |
| `cart.payment_method` | string \| null | | |
| `cart.validation_errors` | (CartValidationErrorMaximumOrderItemQuantity \| CartValidationErrorMaximumOrderTotals \| CartValidationErrorMaximumParentQuantity \| CartValidationErrorMaximumVariantQuantity \| CartValidationErrorMinimumOrderItemQuantity \| CartValidationErrorMinimumOrderTotals \| CartValidationErrorMinimumParentQuantity \| CartValidationErrorMinimumVariantQuantity \| CartValidationErrorPackSize \| CartValidationErrorPricingUnavailable \| CartValidationErrorPricingUnavailableForSelectedQty \| CartValidationErrorQuantityUnavailable)[] | | |
| `cart.validation_errors[].type` | "maximum-order-item-quantity" | | |
| `cart.validation_errors[].overridden` | boolean | | |
| `cart.validation_errors[].maximum` | integer | | |
| `cart.validation_errors[].amount` | number (float) | | |
| `cart.validation_errors[].parent_sku` | string | | |
| `cart.validation_errors[].product_name` | string | | |
| `cart.validation_errors[].minimum` | integer | | |
| `cart.validation_errors[].pack_size` | integer | | |
| `cart.validation_errors[].variant_sku` | string | | |
| `cart.validation_errors[].available_quantity` | integer | | |
| `cart.customer_reference` | string \| null | | |
| `cart.po_number` | string \| null | | |
| `cart.shipping_requested_date` | string \| null | | |
| `cart.custom_fields` | object[] | | The cart's current custom fields. |
| `cart.custom_fields[].name` | string | Yes | |
| `cart.custom_fields[].value` | string | Yes | |
| `item_update_results` | object[] | | |
| `item_update_results[].sku` | string | | |
| `item_update_results[].name` | string \| null | | |
| `item_update_results[].requested_quantity` | number | | |
| `item_update_results[].resultant_quantity` | number | | |
| `item_update_results[].messages` | object[] | | |
| `item_update_results[].messages[].type` | "cannot-adjust-overridden-qty" \| "excessive-lines" \| "not-found" \| "pack-size" \| "product-settings-overridden" \| "qty-excessive" \| "qty-insufficient" \| "qty-unavailable" \| "qty-unavailable-no-clamp" | | |

```json
{
  "cart": {
    "id": "3f2b8c1e-5d4a-4e6f-9b7c-1a2d3e4f5a6b",
    "intent": "ORDER",
    "customer_id": "3f2b8c1e-5d4a-4e6f-9b7c-1a2d3e4f5a6b",
    "shipping_address_id": "3f2b8c1e-5d4a-4e6f-9b7c-1a2d3e4f5a6b",
    "billing_address_id": "3f2b8c1e-5d4a-4e6f-9b7c-1a2d3e4f5a6b",
    "items": [
      {
        "sku": "<sku>",
        "quantity": 0,
        "line_total": {
          "net": "<net>",
          "gross": "<gross>",
          "tax_rate": 0,
          "currency_code": "<currency_code>",
          "tax_inclusive_display": false
        },
        "unit_total": {
          "net": "<net>",
          "gross": "<gross>",
          "tax_rate": 0,
          "currency_code": "<currency_code>",
          "tax_inclusive_display": false
        }
      }
    ],
    "totals": {
      "total": {
        "pre_discount": {
          "net": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "gross": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "tax": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "apportioned_tax_rate": 0,
          "currency": "<currency>"
        },
        "discount": {
          "net": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "gross": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "tax": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "apportioned_tax_rate": 0,
          "currency": "<currency>"
        },
        "charge": {
          "net": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "gross": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "tax": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "apportioned_tax_rate": 0,
          "currency": "<currency>"
        }
      },
      "shipping": {
        "pre_discount": {
          "net": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "gross": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "tax": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "apportioned_tax_rate": 0,
          "currency": "<currency>"
        },
        "discount": {
          "net": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "gross": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "tax": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "apportioned_tax_rate": 0,
          "currency": "<currency>"
        },
        "charge": {
          "net": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "gross": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "tax": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "apportioned_tax_rate": 0,
          "currency": "<currency>"
        }
      },
      "sub_total": {
        "pre_discount": {
          "net": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "gross": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "tax": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "apportioned_tax_rate": 0,
          "currency": "<currency>"
        },
        "discount": {
          "net": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "gross": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "tax": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "apportioned_tax_rate": 0,
          "currency": "<currency>"
        },
        "charge": {
          "net": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "gross": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "tax": {
            "amount": "<amount>",
            "currency_code": "<currency_code>"
          },
          "apportioned_tax_rate": 0,
          "currency": "<currency>"
        }
      }
    },
    "customer_addresses": [
      {
        "id": "<id>",
        "uuid": "<uuid>",
        "first_name": "<first_name>",
        "last_name": "<last_name>",
        "company": "<company>",
        "description": "<description>",
        "address_line_1": "<address_line_1>",
        "address_line_2": "<address_line_2>",
        "city": "<city>",
        "postal_code": "<postal_code>",
        "country_code": "<country_code>",
        "region_code": "<region_code>",
        "phone": "<phone>",
        "external_id": "<external_id>"
      }
    ],
    "shipping_rate_handle": "<shipping_rate_handle>",
    "payment_method": "<payment_method>",
    "validation_errors": [
      {
        "type": "maximum-order-item-quantity",
        "overridden": true,
        "maximum": 0
      }
    ],
    "customer_reference": "<customer_reference>",
    "po_number": "<po_number>",
    "shipping_requested_date": "<shipping_requested_date>",
    "custom_fields": [
      {
        "name": "<name>",
        "value": "<value>"
      }
    ]
  },
  "item_update_results": [
    {
      "sku": "<sku>",
      "name": "<name>",
      "requested_quantity": 0,
      "resultant_quantity": 0,
      "messages": [
        {
          "type": "cannot-adjust-overridden-qty"
        }
      ]
    }
  ]
}
```

#### 404: Cart not found

#### 422: Unprocessable Entity

One of these:

**CartErrorResponse**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | 422 | | HTTP Status code returned from API |
| `title` | "cart-error" | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | "cart-shipping-rate-handle-unavailable" \| "cart-customer-not-found" \| "cart-impersonator-user-not-found" \| "cart-payment-method-unavailable" | | Machine-readable error code |

- **Error**: the standard error body (below).

```json
{
  "detail": "Cart error occurred",
  "status": 422,
  "title": "cart-error",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "cart-shipping-rate-handle-unavailable"
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Complete a cart

URL: https://docs.sparklayer.io/developers/api/ordering/complete-cart
Operation: `POST /api/v1/carts/{id}/complete` (operationId `completeCart`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ordering.yaml

Places the order: checks the shipping rate and payment method, creates a purchase, deletes the cart and returns the new `purchase_id` with a `201`. If the cart has validation errors you haven't listed in `ignore_validation_errors` (use `"*"` to ignore all of them), you get a `422` (`cart-validation-errors`) and no order is created. Because the cart is deleted once the order is placed, repeating the call returns `404`.

`POST /api/v1/carts/{id}/complete`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/carts/9151f21f-43ae-43b4-92f3-f4af67cdf544/complete" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "shipping_rate_handle": "<shipping_rate_handle>",
  "payment_method": "paymentByInvoice",
  "ignore_validation_errors": [
    "maximum-order-item-quantity"
  ]
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The cart's ID: the `cart_id` returned by **Create a cart**. Example: `9151f21f-43ae-43b4-92f3-f4af67cdf544` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `shipping_rate_handle` | string | Yes | The `handle` of one of the shipping methods returned by **Calculate a cart**. |
| `payment_method` | "paymentByInvoice" \| "paymentOnAccount" | Yes | How the customer pays for the order. |
| `ignore_validation_errors` | ("maximum-order-item-quantity" \| "maximum-order-totals" \| "maximum-parent-quantity" \| "maximum-variant-quantity" \| "minimum-order-item-quantity" \| "minimum-order-totals" \| "minimum-parent-quantity" \| "minimum-variant-quantity" \| "pack-size" \| "pricing-unavailable" \| "pricing-unavailable-for-selected-qty" \| "quantity-unavailable" \| "*")[] | Yes | Specify which validation errors to ignore and allow the cart to complete checkout. Passing "*" will ignore all validation errors. |

```json
{
  "shipping_rate_handle": "<shipping_rate_handle>",
  "payment_method": "paymentByInvoice",
  "ignore_validation_errors": [
    "maximum-order-item-quantity"
  ]
}
```

### Responses

#### 201: The order was placed: `purchase_id` is the new purchase.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `purchase_id` | string \| null | | |

```json
{
  "purchase_id": "<purchase_id>"
}
```

#### 404: Cart not found

#### 422: The cart can't be completed: a `cart-error` (such as an unavailable payment method or shipping rate) or `cart-validation-errors` problem. See [Cart errors](https://docs.sparklayer.io/developers/errors.md#cart-errors).

One of these:

**CartErrorResponse**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | 422 | | HTTP Status code returned from API |
| `title` | "cart-error" | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | "cart-shipping-rate-handle-unavailable" \| "cart-customer-not-found" \| "cart-impersonator-user-not-found" \| "cart-payment-method-unavailable" | | Machine-readable error code |

**CartValidationErrorResponse**: Structure for returning error responses as a result of cart validation errors occurring.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | |
| `status` | 422 | | |
| `title` | "cart-validation-errors" | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].validation_error_types` | ("maximum-order-item-quantity" \| "maximum-order-totals" \| "maximum-parent-quantity" \| "maximum-variant-quantity" \| "minimum-order-item-quantity" \| "minimum-order-totals" \| "minimum-parent-quantity" \| "minimum-variant-quantity" \| "pack-size" \| "pricing-unavailable" \| "pricing-unavailable-for-selected-qty" \| "quantity-unavailable")[] | | |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

- **Error**: the standard error body (below).

```json
{
  "detail": "Cart error occurred",
  "status": 422,
  "title": "cart-error",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "cart-shipping-rate-handle-unavailable"
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Calculate a cart

URL: https://docs.sparklayer.io/developers/api/ordering/calculate-cart
Operation: `POST /api/v1/carts/{id}/calculate` (operationId `calculateCart`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ordering.yaml

Calculates the cart's totals, tax, available shipping methods and allowed payment methods, optionally for the shipping rate given in `shipping_rate_handle`. Returns `422` with the error code `cart-empty` if the cart has no items, or `cart-shipping-rate-handle-unavailable` if the SparkLayer shipping rate you chose isn't available for this cart.

`POST /api/v1/carts/{id}/calculate`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/carts/9151f21f-43ae-43b4-92f3-f4af67cdf544/calculate" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "shipping_rate_handle": "<shipping_rate_handle>"
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The cart's ID: the `cart_id` returned by **Create a cart**. Example: `9151f21f-43ae-43b4-92f3-f4af67cdf544` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (optional)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `shipping_rate_handle` | string \| null | | Omitting this will set the carts shipping handle to the first available |

```json
{
  "shipping_rate_handle": "<shipping_rate_handle>"
}
```

### Responses

#### 200: The cart's totals, available shipping methods and allowed payment methods.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `totals` | object | | |
| `totals.total` | object | | |
| `totals.total.pre_discount` | object | | |
| `totals.total.pre_discount.net` | object | | |
| `totals.total.pre_discount.net.amount` | string | | |
| `totals.total.pre_discount.net.currency_code` | string | | |
| `totals.total.pre_discount.gross` | object | | |
| `totals.total.pre_discount.gross.amount` | string | | |
| `totals.total.pre_discount.gross.currency_code` | string | | |
| `totals.total.pre_discount.tax` | object | | |
| `totals.total.pre_discount.tax.amount` | string | | |
| `totals.total.pre_discount.tax.currency_code` | string | | |
| `totals.total.pre_discount.apportioned_tax_rate` | number (float) | | |
| `totals.total.pre_discount.currency` | string | | |
| `totals.total.discount` | object \| null | | |
| `totals.total.discount.net` | object | | |
| `totals.total.discount.net.amount` | string | | |
| `totals.total.discount.net.currency_code` | string | | |
| `totals.total.discount.gross` | object | | |
| `totals.total.discount.gross.amount` | string | | |
| `totals.total.discount.gross.currency_code` | string | | |
| `totals.total.discount.tax` | object | | |
| `totals.total.discount.tax.amount` | string | | |
| `totals.total.discount.tax.currency_code` | string | | |
| `totals.total.discount.apportioned_tax_rate` | number (float) | | |
| `totals.total.discount.currency` | string | | |
| `totals.total.charge` | object | | |
| `totals.total.charge.net` | object | | |
| `totals.total.charge.net.amount` | string | | |
| `totals.total.charge.net.currency_code` | string | | |
| `totals.total.charge.gross` | object | | |
| `totals.total.charge.gross.amount` | string | | |
| `totals.total.charge.gross.currency_code` | string | | |
| `totals.total.charge.tax` | object | | |
| `totals.total.charge.tax.amount` | string | | |
| `totals.total.charge.tax.currency_code` | string | | |
| `totals.total.charge.apportioned_tax_rate` | number (float) | | |
| `totals.total.charge.currency` | string | | |
| `totals.shipping` | object | | |
| `totals.shipping.pre_discount` | object | | |
| `totals.shipping.pre_discount.net` | object | | |
| `totals.shipping.pre_discount.net.amount` | string | | |
| `totals.shipping.pre_discount.net.currency_code` | string | | |
| `totals.shipping.pre_discount.gross` | object | | |
| `totals.shipping.pre_discount.gross.amount` | string | | |
| `totals.shipping.pre_discount.gross.currency_code` | string | | |
| `totals.shipping.pre_discount.tax` | object | | |
| `totals.shipping.pre_discount.tax.amount` | string | | |
| `totals.shipping.pre_discount.tax.currency_code` | string | | |
| `totals.shipping.pre_discount.apportioned_tax_rate` | number (float) | | |
| `totals.shipping.pre_discount.currency` | string | | |
| `totals.shipping.discount` | object \| null | | |
| `totals.shipping.discount.net` | object | | |
| `totals.shipping.discount.net.amount` | string | | |
| `totals.shipping.discount.net.currency_code` | string | | |
| `totals.shipping.discount.gross` | object | | |
| `totals.shipping.discount.gross.amount` | string | | |
| `totals.shipping.discount.gross.currency_code` | string | | |
| `totals.shipping.discount.tax` | object | | |
| `totals.shipping.discount.tax.amount` | string | | |
| `totals.shipping.discount.tax.currency_code` | string | | |
| `totals.shipping.discount.apportioned_tax_rate` | number (float) | | |
| `totals.shipping.discount.currency` | string | | |
| `totals.shipping.charge` | object | | |
| `totals.shipping.charge.net` | object | | |
| `totals.shipping.charge.net.amount` | string | | |
| `totals.shipping.charge.net.currency_code` | string | | |
| `totals.shipping.charge.gross` | object | | |
| `totals.shipping.charge.gross.amount` | string | | |
| `totals.shipping.charge.gross.currency_code` | string | | |
| `totals.shipping.charge.tax` | object | | |
| `totals.shipping.charge.tax.amount` | string | | |
| `totals.shipping.charge.tax.currency_code` | string | | |
| `totals.shipping.charge.apportioned_tax_rate` | number (float) | | |
| `totals.shipping.charge.currency` | string | | |
| `totals.sub_total` | object | | |
| `totals.sub_total.pre_discount` | object | | |
| `totals.sub_total.pre_discount.net` | object | | |
| `totals.sub_total.pre_discount.net.amount` | string | | |
| `totals.sub_total.pre_discount.net.currency_code` | string | | |
| `totals.sub_total.pre_discount.gross` | object | | |
| `totals.sub_total.pre_discount.gross.amount` | string | | |
| `totals.sub_total.pre_discount.gross.currency_code` | string | | |
| `totals.sub_total.pre_discount.tax` | object | | |
| `totals.sub_total.pre_discount.tax.amount` | string | | |
| `totals.sub_total.pre_discount.tax.currency_code` | string | | |
| `totals.sub_total.pre_discount.apportioned_tax_rate` | number (float) | | |
| `totals.sub_total.pre_discount.currency` | string | | |
| `totals.sub_total.discount` | object \| null | | |
| `totals.sub_total.discount.net` | object | | |
| `totals.sub_total.discount.net.amount` | string | | |
| `totals.sub_total.discount.net.currency_code` | string | | |
| `totals.sub_total.discount.gross` | object | | |
| `totals.sub_total.discount.gross.amount` | string | | |
| `totals.sub_total.discount.gross.currency_code` | string | | |
| `totals.sub_total.discount.tax` | object | | |
| `totals.sub_total.discount.tax.amount` | string | | |
| `totals.sub_total.discount.tax.currency_code` | string | | |
| `totals.sub_total.discount.apportioned_tax_rate` | number (float) | | |
| `totals.sub_total.discount.currency` | string | | |
| `totals.sub_total.charge` | object | | |
| `totals.sub_total.charge.net` | object | | |
| `totals.sub_total.charge.net.amount` | string | | |
| `totals.sub_total.charge.net.currency_code` | string | | |
| `totals.sub_total.charge.gross` | object | | |
| `totals.sub_total.charge.gross.amount` | string | | |
| `totals.sub_total.charge.gross.currency_code` | string | | |
| `totals.sub_total.charge.tax` | object | | |
| `totals.sub_total.charge.tax.amount` | string | | |
| `totals.sub_total.charge.tax.currency_code` | string | | |
| `totals.sub_total.charge.apportioned_tax_rate` | number (float) | | |
| `totals.sub_total.charge.currency` | string | | |
| `discounts` | any[] | | |
| `shipping_methods` | object[] | | |
| `shipping_methods[].title` | string | | |
| `shipping_methods[].description` | string \| null | | |
| `shipping_methods[].price_v2` | object | | |
| `shipping_methods[].price_v2.net` | number (float) | | |
| `shipping_methods[].price_v2.gross` | number (float) | | |
| `shipping_methods[].price_v2.tax_rate` | number (float) \| null | | |
| `shipping_methods[].price_v2.currency_code` | string | | |
| `shipping_methods[].price_v2.tax_inclusive_display` | boolean | | Whether the storefront should show the gross amount and label it tax inclusive. Not derivable from tax_rate, since a zero-rated SKU on a tax-inclusive price list has a rate of 0 but must still be labelled. Display only - it says nothing about what is charged. Default: `false`. |
| `shipping_methods[].price_v2_pre_discount` | object \| null | | |
| `shipping_methods[].price_v2_pre_discount.net` | number (float) | | |
| `shipping_methods[].price_v2_pre_discount.gross` | number (float) | | |
| `shipping_methods[].price_v2_pre_discount.tax_rate` | number (float) \| null | | |
| `shipping_methods[].price_v2_pre_discount.currency_code` | string | | |
| `shipping_methods[].price_v2_pre_discount.tax_inclusive_display` | boolean | | Whether the storefront should show the gross amount and label it tax inclusive. Not derivable from tax_rate, since a zero-rated SKU on a tax-inclusive price list has a rate of 0 but must still be labelled. Display only - it says nothing about what is charged. Default: `false`. |
| `shipping_methods[].handle` | string | | |
| `shipping_methods[].cost_type` | string | | |
| `shipping_methods[].cost_language_string` | string \| null | | |
| `allowed_payment_methods` | object | | |
| `allowed_payment_methods.payment_by_invoice` | "AVAILABLE" \| "DISABLED" | | |
| `allowed_payment_methods.payment_on_account` | "AVAILABLE" \| "DISABLED" \| "UNAVAILABLE_DUE_TO_CREDIT" \| "AVAILABLE_CREDIT_LIMIT_HIT" | | |
| `allowed_payment_methods.upfront_payment` | "AVAILABLE" \| "DISABLED" | | |
| `allowed_payment_methods.quote` | "AVAILABLE" \| "DISABLED" | | |
| `selected_shipping_rate_handle` | string \| null | | |
| `selected_payment_method` | string \| null | | |

```json
{
  "totals": {
    "total": {
      "pre_discount": {
        "net": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "gross": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "tax": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "apportioned_tax_rate": 0,
        "currency": "<currency>"
      },
      "discount": {
        "net": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "gross": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "tax": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "apportioned_tax_rate": 0,
        "currency": "<currency>"
      },
      "charge": {
        "net": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "gross": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "tax": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "apportioned_tax_rate": 0,
        "currency": "<currency>"
      }
    },
    "shipping": {
      "pre_discount": {
        "net": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "gross": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "tax": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "apportioned_tax_rate": 0,
        "currency": "<currency>"
      },
      "discount": {
        "net": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "gross": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "tax": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "apportioned_tax_rate": 0,
        "currency": "<currency>"
      },
      "charge": {
        "net": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "gross": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "tax": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "apportioned_tax_rate": 0,
        "currency": "<currency>"
      }
    },
    "sub_total": {
      "pre_discount": {
        "net": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "gross": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "tax": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "apportioned_tax_rate": 0,
        "currency": "<currency>"
      },
      "discount": {
        "net": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "gross": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "tax": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "apportioned_tax_rate": 0,
        "currency": "<currency>"
      },
      "charge": {
        "net": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "gross": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "tax": {
          "amount": "<amount>",
          "currency_code": "<currency_code>"
        },
        "apportioned_tax_rate": 0,
        "currency": "<currency>"
      }
    }
  },
  "discounts": [],
  "shipping_methods": [
    {
      "title": "<title>",
      "description": "<description>",
      "price_v2": {
        "net": 0,
        "gross": 0,
        "tax_rate": 0,
        "currency_code": "<currency_code>",
        "tax_inclusive_display": false
      },
      "price_v2_pre_discount": {
        "net": 0,
        "gross": 0,
        "tax_rate": 0,
        "currency_code": "<currency_code>",
        "tax_inclusive_display": false
      },
      "handle": "<handle>",
      "cost_type": "<cost_type>",
      "cost_language_string": "<cost_language_string>"
    }
  ],
  "allowed_payment_methods": {
    "payment_by_invoice": "AVAILABLE",
    "payment_on_account": "AVAILABLE",
    "upfront_payment": "AVAILABLE",
    "quote": "AVAILABLE"
  },
  "selected_shipping_rate_handle": "<selected_shipping_rate_handle>",
  "selected_payment_method": "<selected_payment_method>"
}
```

#### 404: Cart not found

#### 422: The cart is empty (`cart-empty`) or the chosen shipping rate isn't available (`cart-shipping-rate-handle-unavailable`). See [Cart errors](https://docs.sparklayer.io/developers/errors.md#cart-errors).

One of these:

**CartErrorResponse**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | 422 | | HTTP Status code returned from API |
| `title` | "cart-error" | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | "cart-shipping-rate-handle-unavailable" \| "cart-customer-not-found" \| "cart-impersonator-user-not-found" \| "cart-payment-method-unavailable" | | Machine-readable error code |

- **Error**: the standard error body (below).

```json
{
  "detail": "Cart error occurred",
  "status": 422,
  "title": "cart-error",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "cart-shipping-rate-handle-unavailable"
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Pricing API

URL: https://docs.sparklayer.io/developers/api/pricing

The Pricing API syncs price lists and SKU pricing from your ERP or PIM into SparkLayer, including customer-specific pricing. Covers the flow and endpoints.

With the Pricing API, your price list data comes **directly** from your backend system (such as an ERP, PIM, CRM or iPaaS), and each product SKU is then assigned to a price list in SparkLayer. The diagram shows how this works.

How price list data flows:

1. B2B pricing is managed in price lists that come from your backend system. Each B2B customer is assigned a price list, which gives them their own pricing when they sign in.
2. Price lists are imported into SparkLayer through the SparkLayer API, each with a name, ID and currency code.
3. Price lists are assigned to individual product SKUs. It's common for a SKU to have several price lists.
4. Customers are also assigned a price list in SparkLayer, matching your backend system (e.g. Customer A sees Price list 1, Customer B sees Price list 2).
5. When the customer signs in and visits a product page, the SparkLayer Frontend recognises them (and their price list) and shows their price.

## Typical integration flow

The source system is the external system that sends the pricing data, such as your ERP. A typical sync:

1. Fetch the price lists from the source system.
2. Fetch the SparkLayer price lists with [Get price lists](https://docs.sparklayer.io/developers/api/pricing/get-price-lists-v2.md). To fetch only the lists your integration manages, filter by `source=integration`.
3. Create any price lists missing in SparkLayer with [Create a price list](https://docs.sparklayer.io/developers/api/pricing/create-a-price-list.md). Set `source` to `integration`: the API uses `integration` for price lists from external systems, `custom` (the default) for lists set up in the Dashboard, and `platform` for lists from the eCommerce platform.
4. Collect the prices for each price list from the source system and send them with [Update pricing by price list](https://docs.sparklayer.io/developers/api/pricing/update-pricing-by-price-list.md).

The older `GET /api/v1/price-lists` endpoint is deprecated; use the v2 endpoint for new integrations.

The same process applies to customer-specific pricing: create a price list for the customer, with a reference that links it to them, and send prices to it.

To assign price lists to customers, use SparkLayer customer groups or assign them to customers directly. For direct assignment, see your platform's guide, such as [Shopify metafields](https://docs.sparklayer.io/help/platforms/shopify/metafields.md).

## Data mapping

- Price lists are linked to price list rules.
- Prices are connected to product data by SKU, and each SKU's price belongs to a price list.

Price list data mapping:

- A **price list** links to **price list rules**.
- A **price list** links to **prices**.
- Each **price** is linked to a product **SKU**.

## Checking price list data

To check which price lists a product's prices are in, use the price editor in the SparkLayer Dashboard, at **Pricing > Price editor** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/editor)), or **SparkLayer Wholesale > Pricing > Price editor** in the Shopify app.

## Endpoints

- [GET List price lists](https://docs.sparklayer.io/developers/api/pricing/get-price-lists.md)
- [POST Create a price list](https://docs.sparklayer.io/developers/api/pricing/create-a-price-list.md)
- [GET Get a price list](https://docs.sparklayer.io/developers/api/pricing/get-price-list.md)
- [PATCH Update a price list](https://docs.sparklayer.io/developers/api/pricing/update-a-price-list.md)
- [DELETE Delete a price list](https://docs.sparklayer.io/developers/api/pricing/delete-a-price-list.md)
- [GET List prices in a price list](https://docs.sparklayer.io/developers/api/pricing/get-pricing-by-price-list.md)
- [PATCH Update prices in a price list](https://docs.sparklayer.io/developers/api/pricing/update-pricing-by-price-list.md)
- [GET Get prices for a SKU](https://docs.sparklayer.io/developers/api/pricing/get-pricing-by-sku.md)
- [PATCH Update prices for a SKU](https://docs.sparklayer.io/developers/api/pricing/update-pricing-by-sku.md)
- [PATCH Update prices across price lists](https://docs.sparklayer.io/developers/api/pricing/update-pricing-for-multiple-price-lists.md)
- [POST Calculate prices for SKUs](https://docs.sparklayer.io/developers/api/pricing/calculate-pricing.md)
- [GET List price lists (v2)](https://docs.sparklayer.io/developers/api/pricing/get-price-lists-v2.md)
- [GET List price lists with manual price counts](https://docs.sparklayer.io/developers/api/pricing/get-price-lists-with-manual-price-counts.md)

## Next steps

- [API quickstart](https://docs.sparklayer.io/developers/quickstart.md): get a token and list your price lists.
- [Managing pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md): how merchants work with price lists in the Dashboard.
- [Stock API](https://docs.sparklayer.io/developers/api/stock.md): sync stock levels alongside your prices.


---

# List price lists

URL: https://docs.sparklayer.io/developers/api/pricing/get-price-lists
Operation: `GET /api/v1/price-lists` (operationId `getPriceListsLegacy`)
OpenAPI spec: https://docs.sparklayer.io/openapi/pricing.yaml

Returns every price list for the site as a single, unpaginated array (up to 25,000 price lists from all sources, ordered by name).

This is the legacy version of this endpoint. For new integrations, use `GET /api/v2/price-lists`, which supports pagination, ordering and filtering by source.

`GET /api/v1/price-lists`

> **Deprecated.** See the description for what to use instead.

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/price-lists" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: Every price list, in one unpaginated array.

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].slug` | string | | Slug. Length: min 1, max 64. |
| `[].name` | string | | Name. Length: min 1, max 128. |
| `[].currency_code` | string | | ISO 4217 currency code. Length: min 3, max 3. |
| `[].source` | "custom" \| "platform" \| "integration" | | Integration should be used by external parties, custom is provided to any price lists setup in the dashboard and platform is reserved for the eCommerce platform. Default: `custom`. |
| `[].tax_inclusive_display` | boolean | | When true, storefronts display prices on this price list inclusive of the per-SKU display_tax_rate, labelled as tax inclusive. This changes presentation only - prices are still stored and transacted net. SKUs on the list with no rate, or a rate of 0, display their net price and are still labelled tax inclusive. Default: `false`. |
| `[].rules` | object[] | | Length: max 5. |
| `[].rules[].source_price_list_slug` | string | | Source PriceList slug. Length: min 1, max 64. |
| `[].rules[].adjustment_percentage` | number | | Adjustment percent expressed as a decimal fraction between 0 and 1 - E.g. 15% should be set as 0.15. Min 0, max 1. |
| `[].rules[].adjustment_direction` | "plus" \| "minus" | | Adjustment direction (plus, minus) |
| `[].rules[].currency_exchange_rate` | number \| null | | Exchange rate between the currency of the source price list and the price list to which this rule belongs. If null, the rate will be determined automatically based on current market rates. Min 0.000001. |

```json
[
  {
    "slug": "base-list",
    "name": "Base Price List",
    "currency_code": "GBP",
    "source": "custom",
    "tax_inclusive_display": false,
    "rules": [
      {
        "source_price_list_slug": "base-list",
        "adjustment_percentage": 0.103333,
        "adjustment_direction": "plus",
        "currency_exchange_rate": 1.254324
      }
    ]
  }
]
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/tech-docs"
}
```


---

# Create a price list

URL: https://docs.sparklayer.io/developers/api/pricing/create-a-price-list
Operation: `POST /api/v1/price-lists` (operationId `createPriceList`)
OpenAPI spec: https://docs.sparklayer.io/openapi/pricing.yaml

`slug`, `name` and `currency_code` are required, and `currency_code` must be a valid ISO 4217 code. `source` defaults to `custom`. Returns `400` if a price list with the same slug already exists, or if a rule references a source price list that does not exist.

`POST /api/v1/price-lists`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/price-lists" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "slug": "base-list",
  "name": "Base Price List",
  "currency_code": "GBP",
  "source": "custom",
  "tax_inclusive_display": false,
  "rules": [
    {
      "source_price_list_slug": "base-list",
      "adjustment_percentage": 0.103333,
      "adjustment_direction": "plus",
      "currency_exchange_rate": 1.254324
    }
  ]
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | Slug. Length: min 1, max 64. |
| `name` | string | Yes | Name. Length: min 1, max 128. |
| `currency_code` | string | Yes | ISO 4217 currency code. Length: min 3, max 3. |
| `source` | "custom" \| "platform" \| "integration" | | Integration should be used by external parties, custom is provided to any price lists setup in the dashboard and platform is reserved for the eCommerce platform. Default: `custom`. |
| `tax_inclusive_display` | boolean | | When true, storefronts display prices on this price list inclusive of the per-SKU display_tax_rate, labelled as tax inclusive. This changes presentation only - prices are still stored and transacted net. SKUs on the list with no rate, or a rate of 0, display their net price and are still labelled tax inclusive. Default: `false`. |
| `rules` | object[] | | Length: max 5. |
| `rules[].source_price_list_slug` | string | | Source PriceList slug. Length: min 1, max 64. |
| `rules[].adjustment_percentage` | number | | Adjustment percent expressed as a decimal fraction between 0 and 1 - E.g. 15% should be set as 0.15. Min 0, max 1. |
| `rules[].adjustment_direction` | "plus" \| "minus" | | Adjustment direction (plus, minus) |
| `rules[].currency_exchange_rate` | number \| null | | Exchange rate between the currency of the source price list and the price list to which this rule belongs. If null, the rate will be determined automatically based on current market rates. Min 0.000001. |

```json
{
  "slug": "base-list",
  "name": "Base Price List",
  "currency_code": "GBP",
  "source": "custom",
  "tax_inclusive_display": false,
  "rules": [
    {
      "source_price_list_slug": "base-list",
      "adjustment_percentage": 0.103333,
      "adjustment_direction": "plus",
      "currency_exchange_rate": 1.254324
    }
  ]
}
```

### Responses

#### 200: The new price list.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | | Slug. Length: min 1, max 64. |
| `name` | string | | Name. Length: min 1, max 128. |
| `currency_code` | string | | ISO 4217 currency code. Length: min 3, max 3. |
| `source` | "custom" \| "platform" \| "integration" | | Integration should be used by external parties, custom is provided to any price lists setup in the dashboard and platform is reserved for the eCommerce platform. Default: `custom`. |
| `tax_inclusive_display` | boolean | | When true, storefronts display prices on this price list inclusive of the per-SKU display_tax_rate, labelled as tax inclusive. This changes presentation only - prices are still stored and transacted net. SKUs on the list with no rate, or a rate of 0, display their net price and are still labelled tax inclusive. Default: `false`. |
| `rules` | object[] | | Length: max 5. |
| `rules[].source_price_list_slug` | string | | Source PriceList slug. Length: min 1, max 64. |
| `rules[].adjustment_percentage` | number | | Adjustment percent expressed as a decimal fraction between 0 and 1 - E.g. 15% should be set as 0.15. Min 0, max 1. |
| `rules[].adjustment_direction` | "plus" \| "minus" | | Adjustment direction (plus, minus) |
| `rules[].currency_exchange_rate` | number \| null | | Exchange rate between the currency of the source price list and the price list to which this rule belongs. If null, the rate will be determined automatically based on current market rates. Min 0.000001. |

```json
{
  "slug": "base-list",
  "name": "Base Price List",
  "currency_code": "GBP",
  "source": "custom",
  "tax_inclusive_display": false,
  "rules": [
    {
      "source_price_list_slug": "base-list",
      "adjustment_percentage": 0.103333,
      "adjustment_direction": "plus",
      "currency_exchange_rate": 1.254324
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/tech-docs"
}
```


---

# Get a price list

URL: https://docs.sparklayer.io/developers/api/pricing/get-price-list
Operation: `GET /api/v1/price-lists/{slug}` (operationId `getPriceList`)
OpenAPI spec: https://docs.sparklayer.io/openapi/pricing.yaml

Returns a single price list, including its rules. Returns `404` if no price list exists with that slug.

`GET /api/v1/price-lists/{slug}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/price-lists/base-list" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | The price list's slug. Example: `base-list` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: The price list, including its rules.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | | Slug. Length: min 1, max 64. |
| `name` | string | | Name. Length: min 1, max 128. |
| `currency_code` | string | | ISO 4217 currency code. Length: min 3, max 3. |
| `source` | "custom" \| "platform" \| "integration" | | Integration should be used by external parties, custom is provided to any price lists setup in the dashboard and platform is reserved for the eCommerce platform. Default: `custom`. |
| `tax_inclusive_display` | boolean | | When true, storefronts display prices on this price list inclusive of the per-SKU display_tax_rate, labelled as tax inclusive. This changes presentation only - prices are still stored and transacted net. SKUs on the list with no rate, or a rate of 0, display their net price and are still labelled tax inclusive. Default: `false`. |
| `rules` | object[] | | Length: max 5. |
| `rules[].source_price_list_slug` | string | | Source PriceList slug. Length: min 1, max 64. |
| `rules[].adjustment_percentage` | number | | Adjustment percent expressed as a decimal fraction between 0 and 1 - E.g. 15% should be set as 0.15. Min 0, max 1. |
| `rules[].adjustment_direction` | "plus" \| "minus" | | Adjustment direction (plus, minus) |
| `rules[].currency_exchange_rate` | number \| null | | Exchange rate between the currency of the source price list and the price list to which this rule belongs. If null, the rate will be determined automatically based on current market rates. Min 0.000001. |

```json
{
  "slug": "base-list",
  "name": "Base Price List",
  "currency_code": "GBP",
  "source": "custom",
  "tax_inclusive_display": false,
  "rules": [
    {
      "source_price_list_slug": "base-list",
      "adjustment_percentage": 0.103333,
      "adjustment_direction": "plus",
      "currency_exchange_rate": 1.254324
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/tech-docs"
}
```


---

# Delete a price list

URL: https://docs.sparklayer.io/developers/api/pricing/delete-a-price-list
Operation: `DELETE /api/v1/price-lists/{slug}` (operationId `deletePriceList`)
OpenAPI spec: https://docs.sparklayer.io/openapi/pricing.yaml

Deletes the price list together with its rules and all of its prices. Returns `400` if another price list has a rule that uses this list as its source, and `404` if the price list does not exist.

`DELETE /api/v1/price-lists/{slug}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X DELETE "https://app.sparklayer.io/api/v1/price-lists/base-list" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | The price list's slug. Example: `base-list` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 204: The price list was deleted. No body.

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/tech-docs"
}
```


---

# Update a price list

URL: https://docs.sparklayer.io/developers/api/pricing/update-a-price-list
Operation: `PATCH /api/v1/price-lists/{slug}` (operationId `updatePriceList`)
OpenAPI spec: https://docs.sparklayer.io/openapi/pricing.yaml

Updates only the fields you send (`name`, `currency_code`, `rules` and `tax_inclusive_display`); the slug and source cannot be changed. Sending `rules` replaces all of the existing rules. Changing `currency_code` relabels the prices already on the list with the new currency without converting the amounts. Returns the updated price list, or `404` if it does not exist.

`PATCH /api/v1/price-lists/{slug}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PATCH "https://app.sparklayer.io/api/v1/price-lists/base-list" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "rules": [
    {
      "source_price_list_slug": "base-list",
      "adjustment_percentage": 0.103333,
      "adjustment_direction": "plus",
      "currency_exchange_rate": 1.254324
    }
  ],
  "name": "Base Price List",
  "currency_code": "GBP",
  "tax_inclusive_display": true
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | The price list's slug. Example: `base-list` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `rules` | object[] | | Length: max 5. |
| `rules[].source_price_list_slug` | string | | Source PriceList slug. Length: min 1, max 64. |
| `rules[].adjustment_percentage` | number | | Adjustment percent expressed as a decimal fraction between 0 and 1 - E.g. 15% should be set as 0.15. Min 0, max 1. |
| `rules[].adjustment_direction` | "plus" \| "minus" | | Adjustment direction (plus, minus) |
| `rules[].currency_exchange_rate` | number \| null | | Exchange rate between the currency of the source price list and the price list to which this rule belongs. If null, the rate will be determined automatically based on current market rates. Min 0.000001. |
| `name` | string | | Name. Length: min 1, max 128. |
| `currency_code` | string | | ISO 4217 currency code. Length: min 3, max 3. |
| `tax_inclusive_display` | boolean | | Toggle tax-inclusive display for this price list. |

```json
{
  "rules": [
    {
      "source_price_list_slug": "base-list",
      "adjustment_percentage": 0.103333,
      "adjustment_direction": "plus",
      "currency_exchange_rate": 1.254324
    }
  ],
  "name": "Base Price List",
  "currency_code": "GBP",
  "tax_inclusive_display": true
}
```

### Responses

#### 200: The updated price list.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | | Slug. Length: min 1, max 64. |
| `name` | string | | Name. Length: min 1, max 128. |
| `currency_code` | string | | ISO 4217 currency code. Length: min 3, max 3. |
| `source` | "custom" \| "platform" \| "integration" | | Integration should be used by external parties, custom is provided to any price lists setup in the dashboard and platform is reserved for the eCommerce platform. Default: `custom`. |
| `tax_inclusive_display` | boolean | | When true, storefronts display prices on this price list inclusive of the per-SKU display_tax_rate, labelled as tax inclusive. This changes presentation only - prices are still stored and transacted net. SKUs on the list with no rate, or a rate of 0, display their net price and are still labelled tax inclusive. Default: `false`. |
| `rules` | object[] | | Length: max 5. |
| `rules[].source_price_list_slug` | string | | Source PriceList slug. Length: min 1, max 64. |
| `rules[].adjustment_percentage` | number | | Adjustment percent expressed as a decimal fraction between 0 and 1 - E.g. 15% should be set as 0.15. Min 0, max 1. |
| `rules[].adjustment_direction` | "plus" \| "minus" | | Adjustment direction (plus, minus) |
| `rules[].currency_exchange_rate` | number \| null | | Exchange rate between the currency of the source price list and the price list to which this rule belongs. If null, the rate will be determined automatically based on current market rates. Min 0.000001. |

```json
{
  "slug": "base-list",
  "name": "Base Price List",
  "currency_code": "GBP",
  "source": "custom",
  "tax_inclusive_display": false,
  "rules": [
    {
      "source_price_list_slug": "base-list",
      "adjustment_percentage": 0.103333,
      "adjustment_direction": "plus",
      "currency_exchange_rate": 1.254324
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/tech-docs"
}
```


---

# List price lists (v2)

URL: https://docs.sparklayer.io/developers/api/pricing/get-price-lists-v2
Operation: `GET /api/v2/price-lists` (operationId `getPriceLists`)
OpenAPI spec: https://docs.sparklayer.io/openapi/pricing.yaml

Returns price lists one page at a time. Use `page` (default `1`) and `page_size` (default `100`, maximum `250`) to page through the results, `order_by` to sort them (for example `name:asc` or `updated_at:desc`), and `source` to filter by a comma-separated list of sources. Results are returned in `data`, with a `pagination` object giving `total`, `per_page`, `current_page` and `total_pages`.

Use this endpoint rather than `GET /api/v1/price-lists`, which returns every price list in one unpaginated array.

`GET /api/v2/price-lists`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v2/price-lists" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | integer | | The page of results to fetch. Default: `1`. Min 1. |
| `page_size` | integer | | Number of records per page. Default: `100`. Min 1, max 250. |
| `order_by` | string | | Field to order the search results by. Default: `name:asc`. Pattern: `^(name\|created_at\|updated_at):(asc\|desc)$`. |
| `source` | ("custom" \| "integration" \| "platform")[] | | Only return price lists from these sources, as a comma-separated list: `custom` (set up in the SparkLayer Dashboard), `integration` (created by an external integration) or `platform` (reserved for the eCommerce platform). Defaults to all three. Default: `["custom","integration","platform"]`. |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: One page of price lists in `data`, with the paging details in `pagination`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object[] | | |
| `data[].slug` | string | | Slug. Length: min 1, max 64. |
| `data[].name` | string | | Name. Length: min 1, max 128. |
| `data[].currency_code` | string | | ISO 4217 currency code. Length: min 3, max 3. |
| `data[].source` | "custom" \| "platform" \| "integration" | | Integration should be used by external parties, custom is provided to any price lists setup in the dashboard and platform is reserved for the eCommerce platform. Default: `custom`. |
| `data[].tax_inclusive_display` | boolean | | When true, storefronts display prices on this price list inclusive of the per-SKU display_tax_rate, labelled as tax inclusive. This changes presentation only - prices are still stored and transacted net. SKUs on the list with no rate, or a rate of 0, display their net price and are still labelled tax inclusive. Default: `false`. |
| `data[].rules` | object[] | | Length: max 5. |
| `data[].rules[].source_price_list_slug` | string | | Source PriceList slug. Length: min 1, max 64. |
| `data[].rules[].adjustment_percentage` | number | | Adjustment percent expressed as a decimal fraction between 0 and 1 - E.g. 15% should be set as 0.15. Min 0, max 1. |
| `data[].rules[].adjustment_direction` | "plus" \| "minus" | | Adjustment direction (plus, minus) |
| `data[].rules[].currency_exchange_rate` | number \| null | | Exchange rate between the currency of the source price list and the price list to which this rule belongs. If null, the rate will be determined automatically based on current market rates. Min 0.000001. |
| `pagination` | object | | |
| `pagination.total` | integer | | The total number of available records |
| `pagination.per_page` | integer | | The number of records returned per page |
| `pagination.current_page` | integer | | The current page of results returned |
| `pagination.total_pages` | integer | | the total number of available pages |

```json
{
  "data": [
    {
      "slug": "base-list",
      "name": "Base Price List",
      "currency_code": "GBP",
      "source": "custom",
      "tax_inclusive_display": false,
      "rules": [
        {
          "source_price_list_slug": "base-list",
          "adjustment_percentage": 0.103333,
          "adjustment_direction": "plus",
          "currency_exchange_rate": 1.254324
        }
      ]
    }
  ],
  "pagination": {
    "total": 0,
    "per_page": 0,
    "current_page": 0,
    "total_pages": 0
  }
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/tech-docs"
}
```


---

# List prices in a price list

URL: https://docs.sparklayer.io/developers/api/pricing/get-pricing-by-price-list
Operation: `GET /api/v1/price-lists/{slug}/pricing` (operationId `getPriceListPricingData`)
OpenAPI spec: https://docs.sparklayer.io/openapi/pricing.yaml

Returns every price stored on the price list, one entry per SKU and quantity break, ordered by SKU. Prices derived from the list's rules are not included. Send the request with a `Content-Type: text/csv` header to receive the same data as a CSV file.

Returns `204` with no body if the price list has no prices, and `404` if the price list does not exist.

`GET /api/v1/price-lists/{slug}/pricing`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/price-lists/base-list/pricing" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | The price list's slug. Example: `base-list` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: The prices stored on the price list, as JSON or, when requested, CSV.

`application/json`:

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].quantity` | integer | | The quantity at which the specified price is applicable. This allows for quantity discount pricing to be set up. Default: `1`. Min 1. |
| `[].price` | number (float) | | |
| `[].unit_of_measure` | string \| null | | The unit of measure associated with this quantity. When specifying a unit of measure, it must match the pattern. To remove any value set, either omit the property or set the value as null. Pattern: `^[a-zA-Z0-9-]+$`. |
| `[].display_tax_rate` | number (float) \| null | | Tax rate used only to display a tax-inclusive price, expressed as a whole percentage (10 means 10%). Stored prices remain net and the eCommerce platform remains authoritative for the tax actually charged at checkout. On an update the field has three states: omit it to leave any stored rate unchanged (so a price-only sync never disturbs it), send null to clear it, or send a value to set it. Min 0, max 100. |
| `[].sku` | string | | Length: max 128. |

```json
[
  {
    "quantity": 1,
    "price": 10.49,
    "unit_of_measure": "pallet",
    "display_tax_rate": 10,
    "sku": "SKU-1"
  }
]
```

`text/csv`:

```csv
sku,   quantity, price
SKU-1, 1,        10.99
```

#### 204: The price list has no prices. No body.

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/tech-docs"
}
```


---

# Update prices in a price list

URL: https://docs.sparklayer.io/developers/api/pricing/update-pricing-by-price-list
Operation: `PATCH /api/v1/price-lists/{slug}/pricing` (operationId `updatePriceListPricing`)
OpenAPI spec: https://docs.sparklayer.io/openapi/pricing.yaml

Accepts a JSON array or a CSV file (`Content-Type: text/csv`). Only the SKUs you send are affected: each SKU's existing prices on this list are replaced with the ones supplied.

Validation errors return `400`, usually as an array of `{line, field, message}` objects. Returns `404` if the price list does not exist, and `409` if the update clashed with another one running at the same time, in which case you can retry it.

`PATCH /api/v1/price-lists/{slug}/pricing`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PATCH "https://app.sparklayer.io/api/v1/price-lists/base-list/pricing" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "sku": "SKU-1",
    "display_tax_rate": 10,
    "pricing": [
      {
        "quantity": 1,
        "price": 10.49,
        "unit_of_measure": "pallet"
      }
    ]
  }
]'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | The price list's slug. Example: `base-list` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (required)

Send one of: `application/json`, `text/csv`.

List of sku, quantity and price to update. Partial  updates are supported, meaning only the SKUs present will be  affected. For the given SKUs, existing prices are deleted then  the supplied prices are inserted. If SKU is provided but quantity  and price are blank, all prices for that SKU are removed from the  price list.

#### `application/json`

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].sku` | string | Yes | Length: max 128. |
| `[].display_tax_rate` | number (float) \| null | | Tax rate used only to display a tax-inclusive price, expressed as a whole percentage (10 means 10%). Stored prices remain net and the eCommerce platform remains authoritative for the tax actually charged at checkout. On an update the field has three states: omit it to leave any stored rate unchanged (so a price-only sync never disturbs it), send null to clear it, or send a value to set it. Min 0, max 100. |
| `[].pricing` | object[] | Yes | |
| `[].pricing[].quantity` | integer | Yes | The quantity at which the specified price is applicable. This allows for quantity discount pricing to be set up. Default: `1`. Min 1. |
| `[].pricing[].price` | number (float) | Yes | |
| `[].pricing[].unit_of_measure` | string \| null | | The unit of measure associated with this quantity. When specifying a unit of measure, it must match the pattern. To remove any value set, either omit the property or set the value as null. Pattern: `^[a-zA-Z0-9-]+$`. |

```json
[
  {
    "sku": "SKU-1",
    "display_tax_rate": 10,
    "pricing": [
      {
        "quantity": 1,
        "price": 10.49,
        "unit_of_measure": "pallet"
      }
    ]
  }
]
```

#### `text/csv`

display_tax_rate is optional and applies to the whole SKU on this price list, so it must be the same on every row for a given SKU. A blank cell means the rate is unchanged, so a SKU's rate can be given on just one of its rows, and omitting the column entirely leaves every stored rate alone.

```csv
sku,   quantity, price, unit_of_measure, display_tax_rate
SKU-1, 1,        10.99,                , 10
SKU-1, 10,       9.99,  pallet         , 10
```

### Responses

#### 204: The prices were updated. No body.

#### 400: Validation errors

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].line` | integer | | line of input which the error relates to |
| `[].field` | string | | field which the error relates to |
| `[].message` | string | | human readable description of error |

```json
[
  {
    "line": 0,
    "field": "<field>",
    "message": "<message>"
  }
]
```

#### 404: Price list not found

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/tech-docs"
}
```


---

# Get prices for a SKU

URL: https://docs.sparklayer.io/developers/api/pricing/get-pricing-by-sku
Operation: `GET /api/v1/pricing/{sku}` (operationId `getVariantPricing`)
OpenAPI spec: https://docs.sparklayer.io/openapi/pricing.yaml

Returns the prices stored for the SKU on every price list, grouped by price list. URL-encode the SKU if it contains reserved characters such as `/`. Returns an empty array if the SKU has no prices.

`GET /api/v1/pricing/{sku}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/pricing/SKU-1" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `sku` | string | Yes | The variant SKU. URL-encode it if it contains reserved characters such as `/`. Example: `SKU-1` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: The SKU's prices, grouped by price list.

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].price_list_slug` | string | Yes | Price List Slug |
| `[].display_tax_rate` | number (float) \| null | | Tax rate used only to display a tax-inclusive price, expressed as a whole percentage (10 means 10%). Stored prices remain net and the eCommerce platform remains authoritative for the tax actually charged at checkout. On an update the field has three states: omit it to leave any stored rate unchanged (so a price-only sync never disturbs it), send null to clear it, or send a value to set it. Min 0, max 100. |
| `[].pricing` | object[] | Yes | |
| `[].pricing[].quantity` | integer | | The quantity at which the specified price is applicable. This allows for quantity discount pricing to be set up. Default: `1`. Min 1. |
| `[].pricing[].price` | number (float) | Yes | |
| `[].pricing[].tax_type` | "net" | | **Deprecated.** Net is the only supported value here. Default: `net`. |
| `[].pricing[].unit_of_measure` | string \| null | | The unit of measure associated with this quantity. When specifying a unit of measure, it must match the pattern. To remove any value set, either omit the property or set the value as null. Pattern: `^[a-zA-Z0-9-]+$`. |

```json
[
  {
    "price_list_slug": "base-list",
    "display_tax_rate": 10,
    "pricing": [
      {
        "quantity": 1,
        "price": 10.49,
        "tax_type": "net",
        "unit_of_measure": "pallet"
      }
    ]
  }
]
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/tech-docs"
}
```


---

# Update prices for a SKU

URL: https://docs.sparklayer.io/developers/api/pricing/update-pricing-by-sku
Operation: `PATCH /api/v1/pricing/{sku}` (operationId `updateVariantPricing`)
OpenAPI spec: https://docs.sparklayer.io/openapi/pricing.yaml

This patch endpoint will remove all pricing for the __price list slugs__ provided and apply provided pricing against the provided price lists. It is also important to note you can upload multiple price lists in one call.

`PATCH /api/v1/pricing/{sku}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PATCH "https://app.sparklayer.io/api/v1/pricing/SKU-1" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "price_list_slug": "base-list",
    "display_tax_rate": 10,
    "pricing": [
      {
        "quantity": 1,
        "price": 10.49,
        "tax_type": "net",
        "unit_of_measure": "pallet"
      }
    ]
  }
]'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `sku` | string | Yes | The variant SKU. URL-encode it if it contains reserved characters such as `/`. Example: `SKU-1` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].price_list_slug` | string | Yes | Price List Slug |
| `[].display_tax_rate` | number (float) \| null | | Tax rate used only to display a tax-inclusive price, expressed as a whole percentage (10 means 10%). Stored prices remain net and the eCommerce platform remains authoritative for the tax actually charged at checkout. On an update the field has three states: omit it to leave any stored rate unchanged (so a price-only sync never disturbs it), send null to clear it, or send a value to set it. Min 0, max 100. |
| `[].pricing` | object[] | Yes | |
| `[].pricing[].quantity` | integer | | The quantity at which the specified price is applicable. This allows for quantity discount pricing to be set up. Default: `1`. Min 1. |
| `[].pricing[].price` | number (float) | Yes | |
| `[].pricing[].tax_type` | "net" | | **Deprecated.** Net is the only supported value here. Default: `net`. |
| `[].pricing[].unit_of_measure` | string \| null | | The unit of measure associated with this quantity. When specifying a unit of measure, it must match the pattern. To remove any value set, either omit the property or set the value as null. Pattern: `^[a-zA-Z0-9-]+$`. |

```json
[
  {
    "price_list_slug": "base-list",
    "display_tax_rate": 10,
    "pricing": [
      {
        "quantity": 1,
        "price": 10.49,
        "tax_type": "net",
        "unit_of_measure": "pallet"
      }
    ]
  }
]
```

### Responses

#### 200: Successful response

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].price_list_slug` | string | Yes | Price List Slug |
| `[].display_tax_rate` | number (float) \| null | | Tax rate used only to display a tax-inclusive price, expressed as a whole percentage (10 means 10%). Stored prices remain net and the eCommerce platform remains authoritative for the tax actually charged at checkout. On an update the field has three states: omit it to leave any stored rate unchanged (so a price-only sync never disturbs it), send null to clear it, or send a value to set it. Min 0, max 100. |
| `[].pricing` | object[] | Yes | |
| `[].pricing[].quantity` | integer | | The quantity at which the specified price is applicable. This allows for quantity discount pricing to be set up. Default: `1`. Min 1. |
| `[].pricing[].price` | number (float) | Yes | |
| `[].pricing[].tax_type` | "net" | | **Deprecated.** Net is the only supported value here. Default: `net`. |
| `[].pricing[].unit_of_measure` | string \| null | | The unit of measure associated with this quantity. When specifying a unit of measure, it must match the pattern. To remove any value set, either omit the property or set the value as null. Pattern: `^[a-zA-Z0-9-]+$`. |

```json
[
  {
    "price_list_slug": "base-list",
    "display_tax_rate": 10,
    "pricing": [
      {
        "quantity": 1,
        "price": 10.49,
        "tax_type": "net",
        "unit_of_measure": "pallet"
      }
    ]
  }
]
```

#### 404: Price list not found

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/tech-docs"
}
```


---

# Update prices across price lists

URL: https://docs.sparklayer.io/developers/api/pricing/update-pricing-for-multiple-price-lists
Operation: `PATCH /api/v1/batch-update-pricing` (operationId `updateMultiplePriceListPricing`)
OpenAPI spec: https://docs.sparklayer.io/openapi/pricing.yaml

Accepts a JSON array or a CSV file (`Content-Type: text/csv`); each entry names a SKU, a `price_list_slug` and the prices for that combination. Only the SKU and price list combinations you send are affected, and their existing prices are replaced.

Returns `404` if a referenced price list does not exist, `400` for validation errors (usually as an array of `{line, field, message}` objects), and `409` if the update clashed with another one running at the same time, in which case you can retry it.

`PATCH /api/v1/batch-update-pricing`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PATCH "https://app.sparklayer.io/api/v1/batch-update-pricing" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "sku": "SKU-1",
    "price_list_slug": "example-list",
    "display_tax_rate": 10,
    "pricing": [
      {
        "quantity": 1,
        "price": 10.49,
        "unit_of_measure": "pallet"
      }
    ]
  }
]'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (required)

Send one of: `application/json`, `text/csv`.

List of sku, price list, quantity and price to update. Partial updates are supported, meaning only the SKUs present will be affected. For the given SKUs, existing prices are deleted then the supplied prices are inserted. If a SKU is provided but quantity and price are blank, all prices for that SKU are removed from the price list.

#### `application/json`

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].sku` | string | Yes | Length: max 128. |
| `[].price_list_slug` | string | Yes | |
| `[].display_tax_rate` | number (float) \| null | | Tax rate used only to display a tax-inclusive price, expressed as a whole percentage (10 means 10%). Stored prices remain net and the eCommerce platform remains authoritative for the tax actually charged at checkout. On an update the field has three states: omit it to leave any stored rate unchanged (so a price-only sync never disturbs it), send null to clear it, or send a value to set it. Min 0, max 100. |
| `[].pricing` | object[] | Yes | |
| `[].pricing[].quantity` | integer | Yes | The quantity at which the specified price is applicable. This allows for quantity discount pricing to be set up. Default: `1`. Min 1. |
| `[].pricing[].price` | number (float) | Yes | |
| `[].pricing[].unit_of_measure` | string \| null | | The unit of measure associated with this quantity. When specifying a unit of measure, it must match the pattern. To remove any value set, either omit the property or set the value as null. Pattern: `^[a-zA-Z0-9-]+$`. |

```json
[
  {
    "sku": "SKU-1",
    "price_list_slug": "example-list",
    "display_tax_rate": 10,
    "pricing": [
      {
        "quantity": 1,
        "price": 10.49,
        "unit_of_measure": "pallet"
      }
    ]
  }
]
```

#### `text/csv`

display_tax_rate is optional and applies to the whole SKU on a given price list, so it must be the same on every row for that SKU. A blank cell means the rate is unchanged, so a SKU's rate can be given on just one of its rows, and omitting the column entirely leaves every stored rate alone.

```csv
sku,   price_list_slug, quantity, price, unit_of_measure, display_tax_rate
SKU-1, example-list, 1,        10.99,                   , 10
SKU-1, example-list, 10,       9.99,  pallet            , 10
```

### Responses

#### 204: The prices were updated. No body.

#### 400: Validation errors

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].line` | integer | | line of input which the error relates to |
| `[].field` | string | | field which the error relates to |
| `[].message` | string | | human readable description of error |

```json
[
  {
    "line": 0,
    "field": "<field>",
    "message": "<message>"
  }
]
```

#### 404: Price list not found

#### 500: Internal server error

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/tech-docs"
}
```


---

# Calculate prices for SKUs

URL: https://docs.sparklayer.io/developers/api/pricing/calculate-pricing
Operation: `POST /api/v1/calculate-pricing` (operationId `calculateVariantPricing`)
OpenAPI spec: https://docs.sparklayer.io/openapi/pricing.yaml

Works out the price of each SKU in `skus` from the price lists in `price_list_slugs`, checked in the order given. The first list that has prices for the SKU wins, whether those prices are stored on the list or derived from one of its rules (with currency conversion and the percentage adjustment applied). Prices are always net and are returned as `{number, currency}` objects. Returns an empty array if none of the price lists exist.

`POST /api/v1/calculate-pricing`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/calculate-pricing" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "skus": [
    "TEST01"
  ],
  "price_list_slugs": [
    "a-price-list"
  ]
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `skus` | string[] | | The SKUs to price. |
| `price_list_slugs` | string[] | | The price lists to check, in order: the first list with prices for a SKU is used. |

```json
{
  "skus": [
    "TEST01"
  ],
  "price_list_slugs": [
    "a-price-list"
  ]
}
```

### Responses

#### 200: The calculated prices of each SKU.

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].sku` | string | | SKU |
| `[].display_tax_rate` | number (float) \| null | | Tax rate used only to display a tax-inclusive price, expressed as a whole percentage (10 means 10%). Stored prices remain net and the eCommerce platform remains authoritative for the tax actually charged at checkout. On an update the field has three states: omit it to leave any stored rate unchanged (so a price-only sync never disturbs it), send null to clear it, or send a value to set it. Min 0, max 100. |
| `[].tax_inclusive_display` | boolean | | Whether the winning price list is configured to display prices inclusive of display_tax_rate. Presentation only - the prices returned above are always net. |
| `[].pricing` | object[] | | |
| `[].pricing[].quantity` | integer | | |
| `[].pricing[].price` | object | | |
| `[].pricing[].price.number` | string | | |
| `[].pricing[].price.currency` | string | | |
| `[].pricing[].unit_of_measure` | string \| null | | |

```json
[
  {
    "sku": "TEST01",
    "display_tax_rate": 10,
    "tax_inclusive_display": false,
    "pricing": [
      {
        "quantity": 1,
        "price": {
          "number": "<number>",
          "currency": "<currency>"
        },
        "unit_of_measure": "pallet"
      }
    ]
  }
]
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/tech-docs"
}
```


---

# List price lists with manual price counts

URL: https://docs.sparklayer.io/developers/api/pricing/get-price-lists-with-manual-price-counts
Operation: `GET /api/v2/price-lists-num-manual-prices` (operationId `getPriceListsNumManualPrices`)
OpenAPI spec: https://docs.sparklayer.io/openapi/pricing.yaml

Works like `GET /api/v2/price-lists`, with the same pagination, ordering and `source` filter, but each price list also includes `num_manual_prices`: the number of SKUs with prices stored directly on that list.

`GET /api/v2/price-lists-num-manual-prices`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v2/price-lists-num-manual-prices" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | integer | | The page of results to fetch. Default: `1`. Min 1. |
| `page_size` | integer | | Number of records per page. Default: `100`. Min 1, max 250. |
| `order_by` | string | | Field to order the search results by. Default: `name:asc`. Pattern: `^(name\|created_at\|updated_at):(asc\|desc)$`. |
| `source` | ("custom" \| "integration" \| "platform")[] | | Only return price lists from these sources, as a comma-separated list: `custom` (set up in the SparkLayer Dashboard), `integration` (created by an external integration) or `platform` (reserved for the eCommerce platform). Defaults to all three. Default: `["custom","integration","platform"]`. |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: One page of price lists, each with `num_manual_prices`, in `data`, with the paging details in `pagination`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object[] | | |
| `data[].slug` | string | | Slug. Length: min 1, max 64. |
| `data[].name` | string | | Name. Length: min 1, max 128. |
| `data[].currency_code` | string | | ISO 4217 currency code. Length: min 3, max 3. |
| `data[].source` | "custom" \| "platform" \| "integration" | | Integration should be used by external parties, custom is provided to any price lists setup in the dashboard and platform is reserved for the eCommerce platform. Default: `custom`. |
| `data[].tax_inclusive_display` | boolean | | When true, storefronts display prices on this price list inclusive of the per-SKU display_tax_rate, labelled as tax inclusive. This changes presentation only - prices are still stored and transacted net. SKUs on the list with no rate, or a rate of 0, display their net price and are still labelled tax inclusive. Default: `false`. |
| `data[].rules` | object[] | | Length: max 5. |
| `data[].rules[].source_price_list_slug` | string | | Source PriceList slug. Length: min 1, max 64. |
| `data[].rules[].adjustment_percentage` | number | | Adjustment percent expressed as a decimal fraction between 0 and 1 - E.g. 15% should be set as 0.15. Min 0, max 1. |
| `data[].rules[].adjustment_direction` | "plus" \| "minus" | | Adjustment direction (plus, minus) |
| `data[].rules[].currency_exchange_rate` | number \| null | | Exchange rate between the currency of the source price list and the price list to which this rule belongs. If null, the rate will be determined automatically based on current market rates. Min 0.000001. |
| `data[].num_manual_prices` | integer | | |
| `pagination` | object | | |
| `pagination.total` | integer | | The total number of available records |
| `pagination.per_page` | integer | | The number of records returned per page |
| `pagination.current_page` | integer | | The current page of results returned |
| `pagination.total_pages` | integer | | the total number of available pages |

```json
{
  "data": [
    {
      "slug": "base-list",
      "name": "Base Price List",
      "currency_code": "GBP",
      "source": "custom",
      "tax_inclusive_display": false,
      "rules": [
        {
          "source_price_list_slug": "base-list",
          "adjustment_percentage": 0.103333,
          "adjustment_direction": "plus",
          "currency_exchange_rate": 1.254324
        }
      ],
      "num_manual_prices": 0
    }
  ],
  "pagination": {
    "total": 0,
    "per_page": 0,
    "current_page": 0,
    "total_pages": 0
  }
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/tech-docs"
}
```


---

# Purchasing API

URL: https://docs.sparklayer.io/developers/api/purchasing

Store orders, quotes and carts shown in My Account with the Purchasing API, using purchase identifiers, packages and purchase transactions. Lists all endpoints.

The Purchasing API stores your customers' purchases: carts, quotes, purchases awaiting approval or confirmation, and placed orders. Use it to keep the orders shown in My Account up to date.

> **Purchases aren't sent to your eCommerce platform**
>
> Purchases you create with this API show in the My Account area for your B2B customers, but SparkLayer doesn't push them to your eCommerce platform (such as Shopify). To have an order on your platform too, create it with the platform's own API, such as the [Shopify order API](https://shopify.dev/docs/api/admin-rest/latest/resources/order).

For orders created on your platform to sync to SparkLayer, they need a few properties, which depend on your platform. On Shopify, each order needs:

- The `b2b` tag
- The `sparklayer.order_import` metafield, set to `true`

See [Import order history into SparkLayer](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#import-order-history-into-sparklayer) for the Shopify steps.

## Creating and updating purchases

Create and update purchases with [Create or update a purchase](https://docs.sparklayer.io/developers/api/purchasing/create-update-purchase.md) (`PUT /api/v1/purchases/{lookupBy}/{identifier}`). If no purchase matches `lookupBy` and `identifier`, a new one is created.

- **Send the full purchase every time.** The request replaces the purchase's previous data, so include every field, not just the ones that changed. This prevents stale data and keeps order integrations simple.
- **Leave out calculated fields.** The API calculates them, so don't set them in the request body.
- **Expect a `400` for missing or invalid values.** The error identifies the value to fix.

### Purchase identifiers

The `purchase_identifiers` object holds the purchase's IDs in each system. Use one of them as `lookupBy`:

| Identifier | Description |
| --- | --- |
| `sparklayer` | SparkLayer's ID for the purchase (a UUID). For an order placed through SparkLayer, this is the ID of the SparkLayer cart, which SparkLayer passes to your eCommerce platform when the customer completes checkout. Send it so the order moves from `awaiting_merchant` to `order` and replaces the cart. For other orders, leave it blank. |
| `platform` | The purchase's ID on your eCommerce platform. |
| `internal` | Your ID for the purchase, such as the order number in your ERP or order management system (OMS). |
| `visible` | The ID shown to the customer in their recent orders. |

### Purchase types

Most integrations send purchases of type `order`.

| Purchase type | Description |
| --- | --- |
| `quote` | A quote, with a quote status. |
| `awaiting_approval` | A purchase waiting for another person at the customer's company to approve it, typically with [company users](https://docs.sparklayer.io/help/customers/company-users.md). |
| `awaiting_merchant` | An order completed in SparkLayer but not yet confirmed, because it's pending on the eCommerce platform or the sync hasn't finished. |
| `order` | A finalised order, saved on the eCommerce platform or in your order source of truth, such as an ERP or OMS. |

### Packages

A purchase is mostly made up of packages, which hold the line items, shipping methods, addresses and IDs.

1. When you first create an order, put its line items in a `processing` package.
2. As the order progresses, move items to the relevant packages, such as `shipment`, `return` or `cancelled`. You can have more than one of each, for example for partial shipments.

The order status customers see is calculated from the package dates, such as when each package was created and shipped.

## Purchase transactions

Record payments, refunds and other transactions against a purchase with [Create or update a purchase transaction](https://docs.sparklayer.io/developers/api/purchasing/create-or-update-a-purchase-transaction.md). SparkLayer uses the transactions to calculate the purchase's payment status.

If you record transactions with this API, don't also send them to your eCommerce platform: the same transaction could be recorded twice.

- **Identify the purchase** in the request URL, with `lookupBy` and `identifier`. A purchase can have many transactions, but each needs a unique `platform_id`: the ID the third-party system (such as your payment provider) uses for the transaction. `purchase_spark_id` in the response is read-only, so don't send it.
- **Set the amount** in `total`: positive for a payment, negative for a refund. A `currency_code` is also required. 
- **Choose whether it counts** with `apply_to_balance`.

| `apply_to_balance` | What happens |
| --- | --- |
| `false` | The transaction is stored for information only, and isn't used to calculate the payment status. The [list endpoint](https://docs.sparklayer.io/developers/api/purchasing/get-purchase-transactions.md) returns it, but nothing else happens. Use this for pending or failed transactions, which can help with debugging. |
| `true` | The transaction counts towards the purchase's payment status. SparkLayer also adds an entry to the purchase history, which the customer sees, and adjusts the outstanding balance of the purchase's customer by the `total`. |

Changing a transaction from `true` to `false` deletes the history entry it created, and reverses the change to the customer's balance and payment status.

Use `full_transaction` to store the full transaction, as a JSON string, as the third-party system holds it. SparkLayer stores it as given, without redacting anything, so remove or obscure sensitive data, such as full card numbers, before you send it.

## Endpoints

- [GET Get a purchase](https://docs.sparklayer.io/developers/api/purchasing/get-purchase.md)
- [DELETE Delete a purchase](https://docs.sparklayer.io/developers/api/purchasing/delete-purchase.md)
- [PUT Create or update a purchase](https://docs.sparklayer.io/developers/api/purchasing/create-update-purchase.md)
- [GET List purchases](https://docs.sparklayer.io/developers/api/purchasing/get-purchases.md)
- [GET Get a customer's SKU order stats](https://docs.sparklayer.io/developers/api/purchasing/get-order-stats-for-a-customer.md)
- [GET List purchase history](https://docs.sparklayer.io/developers/api/purchasing/get-purchase-history.md)
- [POST Create a purchase history entry](https://docs.sparklayer.io/developers/api/purchasing/create-a-purchase-history-entry.md)
- [GET List purchase transactions](https://docs.sparklayer.io/developers/api/purchasing/get-purchase-transactions.md)
- [PUT Create or update a purchase transaction](https://docs.sparklayer.io/developers/api/purchasing/create-or-update-a-purchase-transaction.md)
- [GET Get the store currency](https://docs.sparklayer.io/developers/api/purchasing/get-store-currency.md)
- [PUT Update the store currency](https://docs.sparklayer.io/developers/api/purchasing/update-store-currency.md)

## Next steps

- [Authentication](https://docs.sparklayer.io/developers/authentication.md): get an access token for your requests.
- [Ordering API](https://docs.sparklayer.io/developers/api/ordering.md): place orders on behalf of customers.
- [Files API](https://docs.sparklayer.io/developers/api/files.md): download the files customers attach to orders.


---

# Get a purchase

URL: https://docs.sparklayer.io/developers/api/purchasing/get-purchase
Operation: `GET /api/v1/purchases/{lookupBy}/{identifier}` (operationId `getPurchase`)
OpenAPI spec: https://docs.sparklayer.io/openapi/purchasing.yaml

Returns a purchase: a cart, quote, purchase awaiting approval or confirmation, or placed order. Set `lookupBy` to the `purchase_identifiers` field to match on (`sparklayer`, `platform`, `internal` or `visible`) and pass its value in `identifier`; with `sparklayer`, `identifier` must be a UUID. Returns `404` if no purchase matches.

`GET /api/v1/purchases/{lookupBy}/{identifier}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/purchases/platform/123456789" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `lookupBy` | "sparklayer" \| "platform" \| "internal" \| "visible" | Yes | Which of the purchase's `purchase_identifiers` `identifier` is: `sparklayer`, `platform`, `internal` or `visible`. Example: `platform` |
| `identifier` | string \| string (uuid) | Yes | The purchase identifier, of the kind set by `lookupBy`. With `lookupBy=sparklayer` it must be a UUID. Example: `123456789` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Length: min 1. Example: `jones-climbing` |

### Responses

#### 200: The purchase.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | "quote" \| "cart" \| "awaiting_approval" \| "order" \| "awaiting_merchant" \| "archived" \| "platform_archived" \| "pending_recurring_order" | Yes | |
| `purchase_identifiers` | object | Yes | |
| `purchase_identifiers.sparklayer` | string (uuid) \| null | | The identifier SparkLayer uses for the purchase. You will need to generate this if the purchase does not exist. Length: min 1. |
| `purchase_identifiers.platform` | string \| null | | The identifier for the purchase on the e-commerce platform. Length: min 1. |
| `purchase_identifiers.internal` | string \| null | | The identifier for the purchase on your system. Length: min 1. |
| `purchase_identifiers.visible` | string \| null | | The identifier that will be shown to the customer in their recent orders |
| `customer_identifiers` | object | Yes | |
| `customer_identifiers.sparklayer` | string | Yes | The ID of the customer that that order is for. |
| `customer_identifiers.sparklayer_impersonator` | string \| null | | The ID of the sales agent placing the order. |
| `customer_identifiers.sparklayer_impersonator_assignee` | string \| null | | The ID of the sales agent assigned to be responsible for the order. |
| `customer_identifiers.sparklayer_child` | string \| null | | The ID of the company user that placed the order. |
| `company` | object \| null | | Company sections are opt-in; omit this entirely for merchants that do not use them. |
| `company.id` | string (uuid) \| null | | The ID of the company the purchase was placed for. |
| `company.section_id` | string (uuid) \| null | | The ID of the company section the purchase was placed for. |
| `company.section_name` | string \| null | | The section name at the time of purchase, kept so historical purchases stay readable after a section is renamed or deleted. Not filterable. Length: max 128. |
| `payment_method` | "quote" \| "upfrontPayment" \| "paymentOnAccount" \| "paymentByInvoice" \| null | | How the purchase was/will be paid for |
| `dates` | object | Yes | |
| `dates.created_at` | string (date-time) | | The date the purchase was created in SparkLayer (RFC-3339). This is read only - it should not be sent to the API, but will be returned form it |
| `dates.updated_at` | string (date-time) | | The date the purchase was last updated in SparkLayer (RFC-3339). This is read only - it should not be sent to the API, but will be returned form it |
| `dates.placed_at` | string (date-time) \| null | | The date at which the purchase was placed - include user timezone or Z for UTC (RFC-3339) |
| `dates.to_be_placed_at` | string (date-time) \| null | | The date at which the purchase is due to be placed, for a purchase that is scheduled rather than placed immediately (RFC-3339). It can be changed while the purchase is still pending |
| `dates.calculated_submitted_at` | string (date-time) | | The date the purchase was submitted (RFC-3339). This is when the cart is converted into another purchase type. This is read only - it should not be sent to the API, but will be returned form it |
| `dates.expires_at` | string (date-time) | | the date at which the purchase will expire and become archived (RFC-3339). This is read only - it should not be sent to the API, but will be returned form it |
| `dates.payment_due_at` | string (date-time) | | The date at which payment for the purchase is expected |
| `customer_reference` | string \| null | | Additional information that a customer adds to the order |
| `po_number` | string \| null | | PO number for the purchase |
| `shipping_requested_date` | string (date-time) \| null | | The date requested for the delivery to arrive |
| `recurring_purchase` | object \| null | | Present only for a purchase created from a recurring purchase template. Both properties are stored when the purchase is created and ignored on any later update |
| `recurring_purchase.template_id` | string (uuid) \| null | | The recurring purchase template this purchase was created from. Set on creation and ignored on update |
| `recurring_purchase.cancelled_at` | string (date-time) \| null | | The date the customer cancelled the purchase, after which it will not be placed (RFC-3339). Cancelling does not free the date - the template has already had its turn for it |
| `recurring_purchase.to_be_placed_at_initial` | string (date-time) \| null | | The date to_be_placed_at was first set to (RFC-3339). Set on creation and ignored on update, so that rescheduling cannot let the same template produce a second purchase for the same date |
| `currency_code` | string \| null | | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `calculated_shipping_address` | string \| null | | A single string containing all the details of the shipping address. This is read only - it should not be sent to the API, but will be returned form it |
| `calculated_total` | object | | Gross total price of the purchase, calculated by SparkLayer based on package and shipment costs. This is read only - it should not be sent to the API, but will be returned form it |
| `calculated_total.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `calculated_total.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `calculated_total_usd` | object | | Gross total price in USD of the purchase, calculated by SparkLayer based on package and shipment costs. This is read only - it should not be sent to the API, but will be returned form it |
| `calculated_total_usd.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `calculated_total_usd.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `calculated_total_base` | object | | Gross total price in the store's base currency, calculated by SparkLayer. This is read only - it should not be sent to the API, but will be returned from it |
| `calculated_total_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `calculated_total_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `calculated_fulfilment_status` | "incoming" \| "processing" \| "shipped" \| "part_shipped" \| "cancelled" \| "returned" \| "part_returned" \| "varied" \| null | | The status of the order, calculated from the statuses of the individual packages. This is read only - it should not be sent to the API, but will be returned form it |
| `quote` | object \| null | | Quote data |
| `quote.status_slug` | string | | The slug of the quote status applied to this quote |
| `quote.status` | object \| null | | |
| `quote.status.id` | string | | |
| `quote.status.name` | string | | Length: max 45. |
| `quote.status.slug` | string | | Length: max 45. Pattern: `^[a-z0-9-]+$`. |
| `quote.status.default` | boolean | | |
| `quote.status.next` | string \| null | | Length: max 45. Pattern: `^[a-z0-9-]+$`. |
| `quote.status.actions` | ("edit_quote" \| "complete_quote" \| "expiry_date" \| "download_pdf")[] | | |
| `quote.status.created_at` | string (date-time) | | |
| `quote.status.updated_at` | string (date-time) | | |
| `quote.status.deleted_at` | string (date-time) \| null | | |
| `quote.expiry` | string (date-time) \| null | | The date at which the quote is considered expired and no longer valid (RFC-3339) |
| `payment_status` | "unpaid" \| "part_paid" \| "paid" | | That payment status of the order |
| `total_paid` | object | | |
| `total_paid.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `total_paid.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `revision_date` | string (date-time) \| null | | The date at which the purchase was last modified - include user timezone or Z for UTC (RFC-3339) |
| `tax_lines` | object[] | | Tax lines for the purchase. |
| `tax_lines[].title` | string | Yes | The title of the tax line |
| `tax_lines[].amount` | object | Yes | The amount of tax of the tax line |
| `tax_lines[].amount.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `tax_lines[].amount.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `tax_lines[].amount_base` | object | | The amount of tax of the tax line in the store's base currency |
| `tax_lines[].amount_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `tax_lines[].amount_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `tax_lines[].rate` | number (double) \| null | Yes | The rate of the tax. The value represents a percentage e.g. 20 means 20%. Min 0. |
| `billing_address` | object \| null | | |
| `billing_address.name` | string \| null | | |
| `billing_address.company` | string \| null | | |
| `billing_address.address_line1` | string | Yes | |
| `billing_address.address_line2` | string \| null | | |
| `billing_address.city` | string | Yes | |
| `billing_address.region_code` | string \| null | | Length: min 1. |
| `billing_address.postal_code` | string \| null | | |
| `billing_address.country_code` | string | Yes | |
| `billing_address.phone` | string \| null | | |
| `billing_address.sparklayer_id` | string \| null | | |
| `billing_address.first_name` | string \| null | | |
| `billing_address.last_name` | string \| null | | |
| `packages` | (Incoming \| Processing \| Shipment \| Cancelled \| Return)[] | Yes | Packages contained within this purchase |
| `packages[].identifiers` | object | | |
| `packages[].identifiers.sparklayer_package_id` | string (uuid) | Yes | A UUID for the package that must be unique within the purchase. You must generate this yourself |
| `packages[].identifiers.platform` | string \| null | | The identifier for the package on the e-commerce platform. Length: min 1. |
| `packages[].identifiers.internal` | string \| null | | The identifier for the package on your system. Length: min 1. |
| `packages[].identifiers.visible` | string \| null | | The identifier that will be shown to the customer in their recent orders |
| `packages[].accounting_files` | object[] | | |
| `packages[].accounting_files[].identifiers` | object | Yes | |
| `packages[].accounting_files[].identifiers.internal` | string \| null | | The identifier of the purchase file that is used by your system. Length: min 1. |
| `packages[].accounting_files[].identifiers.visible` | string \| null | | The identifier of the purchase file that should be shown to the customer. Default: `INV011`. |
| `packages[].accounting_files[].data` | object | Yes | |
| `packages[].accounting_files[].data.uri` | string (uri) \| null | | |
| `packages[].accounting_files[].data.type` | "uri" | Yes | Default: `uri`. |
| `packages[].accounting_files[].file_type` | "credit" \| "invoice" \| "payment" | Yes | |
| `packages[].line_items` | object[] | | |
| `packages[].line_items[].type` | "custom" \| "product" | | |
| `packages[].line_items[].identifiers` | object | Yes | |
| `packages[].line_items[].identifiers.sparklayer_item_key` | string \| null | | Internally used for tracking line items. For orders, can be set to null. Length: min 1. |
| `packages[].line_items[].identifiers.sparklayer_variant_id` | string \| null | | The ID of the variant on your e-commerce platform. Length: min 1. |
| `packages[].line_items[].identifiers.sku` | string \| null | | Length: max 128. |
| `packages[].line_items[].identifiers.platform` | string \| null | | The identifier for the product on the e-commerce platform. Length: min 1. |
| `packages[].line_items[].identifiers.internal` | string \| null | | The identifier for the product on your system. Length: min 1. |
| `packages[].line_items[].identifiers.visible` | string \| null | | A human-readable identifier for the product |
| `packages[].line_items[].name_parent` | string | Yes | Name of the product |
| `packages[].line_items[].name_child` | string \| null | | Name of the product variant/type |
| `packages[].line_items[].quantity` | number | Yes | |
| `packages[].line_items[].custom_attributes` | object[] | | |
| `packages[].line_items[].custom_attributes[].key` | string | Yes | Key or name of the attribute. |
| `packages[].line_items[].custom_attributes[].value` | string | Yes | Value of the attribute. |
| `packages[].line_items[].line_total` | object \| null | Yes | The total cost of this line. This is nullable only for quotes. |
| `packages[].line_items[].line_total.total_net` | object | Yes | The net cost of the line item. This should be the price after any discounts are applied |
| `packages[].line_items[].line_total.total_net.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].line_total.total_net.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].line_total.total_net_base` | object | | The net cost of the line item in the store's base currency. |
| `packages[].line_items[].line_total.total_net_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].line_total.total_net_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].line_total.total_tax` | object | | The tax on the line item. |
| `packages[].line_items[].line_total.total_tax.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].line_total.total_tax.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].line_total.total_tax_base` | object | | The tax on the line item in the store's base currency. |
| `packages[].line_items[].line_total.total_tax_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].line_total.total_tax_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].line_total.total_gross` | object | | The gross cost of the line item. |
| `packages[].line_items[].line_total.total_gross.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].line_total.total_gross.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].line_total.total_gross_base` | object | | The gross cost of the line item in the store's base currency. |
| `packages[].line_items[].line_total.total_gross_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].line_total.total_gross_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].line_total.discount_net` | object | Yes | The net discount that has already been applied to the total. This is just to show to the end user |
| `packages[].line_items[].line_total.discount_net.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].line_total.discount_net.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].line_total.discount_net_base` | object | | The net discount in the store's base currency. |
| `packages[].line_items[].line_total.discount_net_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].line_total.discount_net_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].line_total.tax_rate` | number (double) \| null | | **Deprecated.** The tax rate to apply to the net total. The value represents a percentage e.g. 20 means 20%. Default: `0`. Min 0. |
| `packages[].line_items[].tax_lines` | object[] | | |
| `packages[].line_items[].tax_lines[].title` | string | Yes | The title of the tax line |
| `packages[].line_items[].tax_lines[].amount` | object | Yes | The amount of tax of the tax line |
| `packages[].line_items[].tax_lines[].amount.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].tax_lines[].amount.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].tax_lines[].amount_base` | object | | The amount of tax of the tax line in the store's base currency |
| `packages[].line_items[].tax_lines[].amount_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].tax_lines[].amount_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].tax_lines[].rate` | number (double) \| null | Yes | The rate of the tax. The value represents a percentage e.g. 20 means 20%. Min 0. |
| `packages[].shipping_method` | object \| null | | Details of how the package was/will be shipped |
| `packages[].shipping_method.sku` | string \| null | | SKU that identifies the shipping method used. Length: min 1. |
| `packages[].shipping_method.name` | string | Yes | The friendly/human-readable name for the shipping method |
| `packages[].shipping_method.line_total` | object | Yes | Cost of the shipment |
| `packages[].shipping_method.line_total.total_net` | object | Yes | The net cost of the line item. This should be the price after any discounts are applied |
| `packages[].shipping_method.line_total.total_net.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.line_total.total_net.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.line_total.total_net_base` | object | | The net cost of the line item in the store's base currency. |
| `packages[].shipping_method.line_total.total_net_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.line_total.total_net_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.line_total.total_tax` | object | | The tax on the line item. |
| `packages[].shipping_method.line_total.total_tax.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.line_total.total_tax.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.line_total.total_tax_base` | object | | The tax on the line item in the store's base currency. |
| `packages[].shipping_method.line_total.total_tax_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.line_total.total_tax_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.line_total.total_gross` | object | | The gross cost of the line item. |
| `packages[].shipping_method.line_total.total_gross.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.line_total.total_gross.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.line_total.total_gross_base` | object | | The gross cost of the line item in the store's base currency. |
| `packages[].shipping_method.line_total.total_gross_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.line_total.total_gross_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.line_total.discount_net` | object | Yes | The net discount that has already been applied to the total. This is just to show to the end user |
| `packages[].shipping_method.line_total.discount_net.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.line_total.discount_net.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.line_total.discount_net_base` | object | | The net discount in the store's base currency. |
| `packages[].shipping_method.line_total.discount_net_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.line_total.discount_net_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.line_total.tax_rate` | number (double) \| null | | **Deprecated.** The tax rate to apply to the net total. The value represents a percentage e.g. 20 means 20%. Default: `0`. Min 0. |
| `packages[].shipping_method.tax_lines` | object[] | | |
| `packages[].shipping_method.tax_lines[].title` | string | Yes | The title of the tax line |
| `packages[].shipping_method.tax_lines[].amount` | object | Yes | The amount of tax of the tax line |
| `packages[].shipping_method.tax_lines[].amount.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.tax_lines[].amount.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.tax_lines[].amount_base` | object | | The amount of tax of the tax line in the store's base currency |
| `packages[].shipping_method.tax_lines[].amount_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.tax_lines[].amount_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.tax_lines[].rate` | number (double) \| null | Yes | The rate of the tax. The value represents a percentage e.g. 20 means 20%. Min 0. |
| `packages[].shipping_address` | object \| null | | |
| `packages[].shipping_address.name` | string \| null | | |
| `packages[].shipping_address.company` | string \| null | | |
| `packages[].shipping_address.address_line1` | string | Yes | |
| `packages[].shipping_address.address_line2` | string \| null | | |
| `packages[].shipping_address.city` | string | Yes | |
| `packages[].shipping_address.region_code` | string \| null | | Length: min 1. |
| `packages[].shipping_address.postal_code` | string \| null | | |
| `packages[].shipping_address.country_code` | string | Yes | |
| `packages[].shipping_address.phone` | string \| null | | |
| `packages[].shipping_address.sparklayer_id` | string \| null | | |
| `packages[].shipping_address.first_name` | string \| null | | |
| `packages[].shipping_address.last_name` | string \| null | | |
| `packages[].shipments` | object[] | | Carrier and tracking details for the shipment |
| `packages[].shipments[].carrier` | string | Yes | |
| `packages[].shipments[].carrier_id` | string | Yes | The tracking number/ID used by the carrier |
| `packages[].shipments[].tracking_url` | string (uri) \| null | | The URL the customer can use to track their shipment |
| `packages[].type` | "incoming" | | |
| `packages[].dates` | object | | |
| `packages[].dates.shipped_at` | string (date-time) | Yes | The date at which the package was shipped - include user timezone or Z for UTC (RFC-3339) |
| `accounting_files` | object[] | Yes | Any accounting files associated with this package e.g. invoices |
| `accounting_files[].identifiers` | object | Yes | |
| `accounting_files[].identifiers.internal` | string \| null | | The identifier of the purchase file that is used by your system. Length: min 1. |
| `accounting_files[].identifiers.visible` | string \| null | | The identifier of the purchase file that should be shown to the customer. Default: `INV011`. |
| `accounting_files[].data` | object | Yes | |
| `accounting_files[].data.uri` | string (uri) \| null | | |
| `accounting_files[].data.type` | "uri" | Yes | Default: `uri`. |
| `accounting_files[].file_type` | "credit" \| "invoice" \| "payment" | Yes | |
| `custom_fields` | object[] | Yes | Extra information for the purchase. This will be shown to the customer in their recent orders |
| `custom_fields[].name` | string | Yes | Name/identifier for the custom field. Length: min 1. |
| `custom_fields[].value` | string \| null | | Data for the custom field |
| `metadata` | object[] | | Extra information for the purchase. This not will be shown to the customer |
| `metadata[].name` | string | Yes | Name/identifier for the metadata. Length: min 1. |
| `metadata[].value` | string | Yes | Data for the metadata |

```json
{
  "type": "order",
  "purchase_identifiers": {
    "sparklayer": "63428136-658f-48a6-beb7-7f333dfd9686",
    "platform": "123456789",
    "internal": "<internal>",
    "visible": "B2B01123"
  },
  "customer_identifiers": {
    "sparklayer": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "sparklayer_impersonator": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "sparklayer_impersonator_assignee": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "sparklayer_child": "4217ba4f-7618-4e3b-b1af-9055639b18d1"
  },
  "company": {
    "id": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "section_id": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "section_name": "Bristol"
  },
  "payment_method": "quote",
  "dates": {
    "created_at": "2020-01-01T00:00:00+02:00",
    "updated_at": "2020-01-01T00:00:00+02:00",
    "placed_at": "2020-01-01T00:00:00+02:00",
    "to_be_placed_at": "2020-01-01T00:00:00+02:00",
    "calculated_submitted_at": "2020-01-01T00:00:00+02:00",
    "expires_at": "2020-01-01T00:00:00+02:00",
    "payment_due_at": "2020-01-01T00:00:00+02:00"
  },
  "customer_reference": "Please deliver to the back of the store",
  "po_number": "PO-001",
  "shipping_requested_date": "2020-01-01T00:00:00+02:00",
  "recurring_purchase": {
    "template_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "cancelled_at": "2020-01-01T00:00:00+02:00",
    "to_be_placed_at_initial": "2020-01-01T00:00:00+02:00"
  },
  "currency_code": "GBP",
  "calculated_shipping_address": "John Spark, SparkLayer, SparkLayer HQ, Example City, 12345",
  "calculated_total": {
    "number": "15.99",
    "currency": "GBP"
  },
  "calculated_total_usd": {
    "number": "15.99",
    "currency": "GBP"
  },
  "calculated_total_base": {
    "number": "15.99",
    "currency": "GBP"
  },
  "calculated_fulfilment_status": "processing",
  "quote": {
    "status_slug": "<status_slug>",
    "status": {
      "id": "<id>",
      "name": "<name>",
      "slug": "<slug>",
      "default": true,
      "next": "<next>",
      "actions": [
        "edit_quote"
      ],
      "created_at": "2026-01-31T09:00:00Z",
      "updated_at": "2026-01-31T09:00:00Z",
      "deleted_at": "2026-01-31T09:00:00Z"
    },
    "expiry": "2020-01-01T00:00:00+02:00"
  },
  "payment_status": "unpaid",
  "total_paid": {
    "number": "15.99",
    "currency": "GBP"
  },
  "revision_date": "2020-01-01T00:00:00+02:00",
  "tax_lines": [
    {
      "title": "HST",
      "amount": {
        "number": "15.99",
        "currency": "GBP"
      },
      "amount_base": {
        "number": "15.99",
        "currency": "GBP"
      },
      "rate": 20
    }
  ],
  "billing_address": {
    "name": "Tom Jones",
    "company": "Tom Jones Hardware Ltd",
    "address_line1": "7 Philosophy way",
    "address_line2": null,
    "city": "Willerby",
    "region_code": null,
    "postal_code": "BJ6 9MK",
    "country_code": "GB",
    "phone": "0123456789",
    "sparklayer_id": "63428136-658f-48a6-beb7-7f333dfd9686",
    "first_name": "Tom",
    "last_name": "Jones"
  },
  "packages": [
    {
      "identifiers": {
        "sparklayer_package_id": "63428136-658f-48a6-beb7-7f333dfd9686",
        "platform": "123456789",
        "internal": "<internal>",
        "visible": "<visible>"
      },
      "accounting_files": [
        {
          "identifiers": {
            "internal": "INV011",
            "visible": "INV011"
          },
          "data": {
            "uri": "https://example.com",
            "type": "uri"
          },
          "file_type": "invoice"
        }
      ],
      "line_items": [
        {
          "type": "custom",
          "identifiers": {
            "sparklayer_item_key": "<sparklayer_item_key>",
            "sparklayer_variant_id": "45552423353839",
            "sku": "CAT-MUG",
            "platform": "123456789",
            "internal": "<internal>",
            "visible": "<visible>"
          },
          "name_parent": "T-Shirt",
          "name_child": "Red",
          "quantity": 4,
          "custom_attributes": [
            {
              "key": "mug text",
              "value": "best company ever"
            }
          ],
          "line_total": {
            "total_net": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_net_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_tax": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_tax_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_gross": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_gross_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "discount_net": {
              "number": "15.99",
              "currency": "GBP"
            },
            "discount_net_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "tax_rate": 20
          },
          "tax_lines": [
            {
              "title": "HST",
              "amount": {
                "number": "15.99",
                "currency": "GBP"
              },
              "amount_base": {
                "number": "15.99",
                "currency": "GBP"
              },
              "rate": 20
            }
          ]
        }
      ],
      "shipping_method": {
        "sku": "SHIP-ECO",
        "name": "Standard Shipping",
        "line_total": {
          "total_net": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_net_base": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_tax": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_tax_base": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_gross": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_gross_base": {
            "number": "15.99",
            "currency": "GBP"
          },
          "discount_net": {
            "number": "15.99",
            "currency": "GBP"
          },
          "discount_net_base": {
            "number": "15.99",
            "currency": "GBP"
          },
          "tax_rate": 20
        },
        "tax_lines": [
          {
            "title": "HST",
            "amount": {
              "number": "15.99",
              "currency": "GBP"
            },
            "amount_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "rate": 20
          }
        ]
      },
      "shipping_address": {
        "name": "Tom Jones",
        "company": "Tom Jones Hardware Ltd",
        "address_line1": "7 Philosophy way",
        "address_line2": null,
        "city": "Willerby",
        "region_code": null,
        "postal_code": "BJ6 9MK",
        "country_code": "GB",
        "phone": "0123456789",
        "sparklayer_id": "63428136-658f-48a6-beb7-7f333dfd9686",
        "first_name": "Tom",
        "last_name": "Jones"
      },
      "shipments": [
        {
          "carrier": "Carrier Company Ltd",
          "carrier_id": "<carrier_id>",
          "tracking_url": "https://example.com"
        }
      ],
      "type": "incoming"
    }
  ],
  "accounting_files": [
    {
      "identifiers": {
        "internal": "INV011",
        "visible": "INV011"
      },
      "data": {
        "uri": "https://example.com",
        "type": "uri"
      },
      "file_type": "invoice"
    }
  ],
  "custom_fields": [
    {
      "name": "delivery-date",
      "value": "2023-10-28"
    }
  ],
  "metadata": [
    {
      "name": "example-key",
      "value": "1234"
    }
  ]
}
```

#### 404: Not found.

`application/problem+json`: the standard error body (below).

#### 500: An unexpected error.

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |
| `errors` | object[] | | |
| `errors[].code` | string | | A machine-readable error message |
| `errors[].property` | string | | The offending property |
| `errors[].message` | string | | A human-readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://hub.sparklayer.io/tech-docs",
  "errors": [
    {
      "code": "unique-constraint-violation",
      "property": "purchase_identifiers.sparklayer",
      "message": "Each stock level must have a unique stock location and sku combination"
    }
  ]
}
```


---

# Create or update a purchase

URL: https://docs.sparklayer.io/developers/api/purchasing/create-update-purchase
Operation: `PUT /api/v1/purchases/{lookupBy}/{identifier}` (operationId `createUpdatePurchase`)
OpenAPI spec: https://docs.sparklayer.io/openapi/purchasing.yaml

Creates the purchase if none matches `lookupBy` and `identifier`, otherwise replaces it, and returns the stored purchase. The request replaces all of the purchase's data, so always send the full purchase rather than only the fields that changed, and leave out calculated fields: the API calculates them. For an order placed through SparkLayer, look it up with `lookupBy=sparklayer` and the SparkLayer cart ID, so the order replaces the cart.

Purchases created here appear in My Account but aren't sent to your eCommerce platform. Returns `400` if a required value is missing or invalid, `403` if the request tries to change the purchase's SparkLayer ID, and `409` if it conflicts with the stored purchase.

`PUT /api/v1/purchases/{lookupBy}/{identifier}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PUT "https://app.sparklayer.io/api/v1/purchases/platform/123456789" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "order",
  "purchase_identifiers": {
    "sparklayer": "63428136-658f-48a6-beb7-7f333dfd9686",
    "platform": "123456789",
    "internal": "<internal>",
    "visible": "B2B01123"
  },
  "customer_identifiers": {
    "sparklayer": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "sparklayer_impersonator": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "sparklayer_impersonator_assignee": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "sparklayer_child": "4217ba4f-7618-4e3b-b1af-9055639b18d1"
  },
  "company": {
    "id": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "section_id": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "section_name": "Bristol"
  },
  "payment_method": "quote",
  "dates": {
    "placed_at": "2020-01-01T00:00:00+02:00",
    "to_be_placed_at": "2020-01-01T00:00:00+02:00",
    "payment_due_at": "2020-01-01T00:00:00+02:00"
  },
  "customer_reference": "Please deliver to the back of the store",
  "po_number": "PO-001",
  "shipping_requested_date": "2020-01-01T00:00:00+02:00",
  "recurring_purchase": {
    "template_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "cancelled_at": "2020-01-01T00:00:00+02:00",
    "to_be_placed_at_initial": "2020-01-01T00:00:00+02:00"
  },
  "currency_code": "GBP",
  "currency_code_base": "GBP",
  "calculated_total": {
    "number": "15.99",
    "currency": "GBP"
  },
  "calculated_total_usd": {
    "number": "15.99",
    "currency": "GBP"
  },
  "calculated_total_base": {
    "number": "15.99",
    "currency": "GBP"
  },
  "quote": {
    "status_slug": "<status_slug>",
    "status": {
      "id": "<id>",
      "name": "<name>",
      "slug": "<slug>",
      "default": true,
      "next": "<next>",
      "actions": [
        "edit_quote"
      ],
      "created_at": "2026-01-31T09:00:00Z",
      "updated_at": "2026-01-31T09:00:00Z",
      "deleted_at": "2026-01-31T09:00:00Z"
    },
    "expiry": "2020-01-01T00:00:00+02:00"
  },
  "payment_status": "unpaid",
  "total_paid": {
    "number": "15.99",
    "currency": "GBP"
  },
  "revision_date": "2020-01-01T00:00:00+02:00",
  "tax_lines": [
    {
      "title": "HST",
      "amount": {
        "number": "15.99",
        "currency": "GBP"
      },
      "amount_base": {
        "number": "15.99",
        "currency": "GBP"
      },
      "rate": 20
    }
  ],
  "billing_address": {
    "name": "Tom Jones",
    "company": "Tom Jones Hardware Ltd",
    "address_line1": "7 Philosophy way",
    "address_line2": null,
    "city": "Willerby",
    "region_code": null,
    "postal_code": "BJ6 9MK",
    "country_code": "GB",
    "phone": "0123456789",
    "sparklayer_id": "63428136-658f-48a6-beb7-7f333dfd9686",
    "first_name": "Tom",
    "last_name": "Jones"
  },
  "packages": [
    {
      "identifiers": {
        "sparklayer_package_id": "63428136-658f-48a6-beb7-7f333dfd9686",
        "platform": "123456789",
        "internal": "<internal>",
        "visible": "<visible>"
      },
      "accounting_files": [
        {
          "identifiers": {
            "internal": "INV011",
            "visible": "INV011"
          },
          "data": {
            "uri": "https://example.com",
            "type": "uri"
          },
          "file_type": "invoice"
        }
      ],
      "line_items": [
        {
          "type": "custom",
          "identifiers": {
            "sparklayer_item_key": "<sparklayer_item_key>",
            "sparklayer_variant_id": "45552423353839",
            "sku": "CAT-MUG",
            "platform": "123456789",
            "internal": "<internal>",
            "visible": "<visible>"
          },
          "name_parent": "T-Shirt",
          "name_child": "Red",
          "quantity": 4,
          "custom_attributes": [
            {
              "key": "mug text",
              "value": "best company ever"
            }
          ],
          "line_total": {
            "total_net": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_net_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_tax": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_tax_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_gross": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_gross_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "discount_net": {
              "number": "15.99",
              "currency": "GBP"
            },
            "discount_net_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "tax_rate": 20
          },
          "tax_lines": [
            {
              "title": "HST",
              "amount": {
                "number": "15.99",
                "currency": "GBP"
              },
              "amount_base": {
                "number": "15.99",
                "currency": "GBP"
              },
              "rate": 20
            }
          ]
        }
      ],
      "shipping_method": {
        "sku": "SHIP-ECO",
        "name": "Standard Shipping",
        "line_total": {
          "total_net": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_net_base": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_tax": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_tax_base": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_gross": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_gross_base": {
            "number": "15.99",
            "currency": "GBP"
          },
          "discount_net": {
            "number": "15.99",
            "currency": "GBP"
          },
          "discount_net_base": {
            "number": "15.99",
            "currency": "GBP"
          },
          "tax_rate": 20
        },
        "tax_lines": [
          {
            "title": "HST",
            "amount": {
              "number": "15.99",
              "currency": "GBP"
            },
            "amount_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "rate": 20
          }
        ]
      },
      "shipping_address": {
        "name": "Tom Jones",
        "company": "Tom Jones Hardware Ltd",
        "address_line1": "7 Philosophy way",
        "address_line2": null,
        "city": "Willerby",
        "region_code": null,
        "postal_code": "BJ6 9MK",
        "country_code": "GB",
        "phone": "0123456789",
        "sparklayer_id": "63428136-658f-48a6-beb7-7f333dfd9686",
        "first_name": "Tom",
        "last_name": "Jones"
      },
      "shipments": [
        {
          "carrier": "Carrier Company Ltd",
          "carrier_id": "<carrier_id>",
          "tracking_url": "https://example.com"
        }
      ],
      "type": "incoming"
    }
  ],
  "accounting_files": [
    {
      "identifiers": {
        "internal": "INV011",
        "visible": "INV011"
      },
      "data": {
        "uri": "https://example.com",
        "type": "uri"
      },
      "file_type": "invoice"
    }
  ],
  "custom_fields": [
    {
      "name": "delivery-date",
      "value": "2023-10-28"
    }
  ],
  "metadata": [
    {
      "name": "example-key",
      "value": "1234"
    }
  ]
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `lookupBy` | "sparklayer" \| "platform" \| "internal" \| "visible" | Yes | Which of the purchase's `purchase_identifiers` `identifier` is: `sparklayer`, `platform`, `internal` or `visible`. Example: `platform` |
| `identifier` | string \| string (uuid) | Yes | The purchase identifier, of the kind set by `lookupBy`. With `lookupBy=sparklayer` it must be a UUID. Example: `123456789` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Length: min 1. Example: `jones-climbing` |

### Request body (`application/json`) (required)

SparkLayer purchase object.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | "quote" \| "cart" \| "awaiting_approval" \| "order" \| "awaiting_merchant" \| "archived" \| "platform_archived" \| "pending_recurring_order" | Yes | |
| `purchase_identifiers` | object | Yes | |
| `purchase_identifiers.sparklayer` | string (uuid) \| null | | The identifier SparkLayer uses for the purchase. You will need to generate this if the purchase does not exist. Length: min 1. |
| `purchase_identifiers.platform` | string \| null | | The identifier for the purchase on the e-commerce platform. Length: min 1. |
| `purchase_identifiers.internal` | string \| null | | The identifier for the purchase on your system. Length: min 1. |
| `purchase_identifiers.visible` | string \| null | | The identifier that will be shown to the customer in their recent orders |
| `customer_identifiers` | object | Yes | |
| `customer_identifiers.sparklayer` | string | Yes | The ID of the customer that that order is for. |
| `customer_identifiers.sparklayer_impersonator` | string \| null | | The ID of the sales agent placing the order. |
| `customer_identifiers.sparklayer_impersonator_assignee` | string \| null | | The ID of the sales agent assigned to be responsible for the order. |
| `customer_identifiers.sparklayer_child` | string \| null | | The ID of the company user that placed the order. |
| `company` | object \| null | | Company sections are opt-in; omit this entirely for merchants that do not use them. |
| `company.id` | string (uuid) \| null | | The ID of the company the purchase was placed for. |
| `company.section_id` | string (uuid) \| null | | The ID of the company section the purchase was placed for. |
| `company.section_name` | string \| null | | The section name at the time of purchase, kept so historical purchases stay readable after a section is renamed or deleted. Not filterable. Length: max 128. |
| `payment_method` | "quote" \| "upfrontPayment" \| "paymentOnAccount" \| "paymentByInvoice" \| null | | How the purchase was/will be paid for |
| `dates` | object | Yes | |
| `dates.placed_at` | string (date-time) \| null | | The date at which the purchase was placed - include user timezone or Z for UTC (RFC-3339) |
| `dates.to_be_placed_at` | string (date-time) \| null | | The date at which the purchase is due to be placed, for a purchase that is scheduled rather than placed immediately (RFC-3339). It can be changed while the purchase is still pending |
| `dates.payment_due_at` | string (date-time) | | The date at which payment for the purchase is expected |
| `customer_reference` | string \| null | | Additional information that a customer adds to the order |
| `po_number` | string \| null | | PO number for the purchase |
| `shipping_requested_date` | string (date-time) \| null | | The date requested for the delivery to arrive |
| `recurring_purchase` | object \| null | | Present only for a purchase created from a recurring purchase template. Both properties are stored when the purchase is created and ignored on any later update |
| `recurring_purchase.template_id` | string (uuid) \| null | | The recurring purchase template this purchase was created from. Set on creation and ignored on update |
| `recurring_purchase.cancelled_at` | string (date-time) \| null | | The date the customer cancelled the purchase, after which it will not be placed (RFC-3339). Cancelling does not free the date - the template has already had its turn for it |
| `recurring_purchase.to_be_placed_at_initial` | string (date-time) \| null | | The date to_be_placed_at was first set to (RFC-3339). Set on creation and ignored on update, so that rescheduling cannot let the same template produce a second purchase for the same date |
| `currency_code` | string \| null | | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `currency_code_base` | string \| null | | The 3 letter currency code of the store's base currency. Length: min 3, max 3. |
| `calculated_total` | object | | Gross total price of the purchase, calculated by SparkLayer based on package and shipment costs. This is read only - it should not be sent to the API, but will be returned form it |
| `calculated_total.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `calculated_total.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `calculated_total_usd` | object | | Gross total price in USD of the purchase, calculated by SparkLayer based on package and shipment costs. This is read only - it should not be sent to the API, but will be returned form it |
| `calculated_total_usd.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `calculated_total_usd.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `calculated_total_base` | object | | Gross total price in the store's base currency, calculated by SparkLayer. This is read only - it should not be sent to the API, but will be returned from it |
| `calculated_total_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `calculated_total_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `quote` | object \| null | | Quote data |
| `quote.status_slug` | string | | The slug of the quote status applied to this quote |
| `quote.status` | object \| null | | |
| `quote.status.id` | string | | |
| `quote.status.name` | string | | Length: max 45. |
| `quote.status.slug` | string | | Length: max 45. Pattern: `^[a-z0-9-]+$`. |
| `quote.status.default` | boolean | | |
| `quote.status.next` | string \| null | | Length: max 45. Pattern: `^[a-z0-9-]+$`. |
| `quote.status.actions` | ("edit_quote" \| "complete_quote" \| "expiry_date" \| "download_pdf")[] | | |
| `quote.status.created_at` | string (date-time) | | |
| `quote.status.updated_at` | string (date-time) | | |
| `quote.status.deleted_at` | string (date-time) \| null | | |
| `quote.expiry` | string (date-time) \| null | | The date at which the quote is considered expired and no longer valid (RFC-3339) |
| `payment_status` | "unpaid" \| "part_paid" \| "paid" | | That payment status of the order |
| `total_paid` | object | | |
| `total_paid.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `total_paid.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `revision_date` | string (date-time) \| null | | The date at which the purchase was last modified - include user timezone or Z for UTC (RFC-3339) |
| `tax_lines` | object[] | | Tax lines for the purchase. |
| `tax_lines[].title` | string | Yes | The title of the tax line |
| `tax_lines[].amount` | object | Yes | The amount of tax of the tax line |
| `tax_lines[].amount.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `tax_lines[].amount.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `tax_lines[].amount_base` | object | | The amount of tax of the tax line in the store's base currency |
| `tax_lines[].amount_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `tax_lines[].amount_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `tax_lines[].rate` | number (double) \| null | Yes | The rate of the tax. The value represents a percentage e.g. 20 means 20%. Min 0. |
| `billing_address` | object \| null | | |
| `billing_address.name` | string \| null | | |
| `billing_address.company` | string \| null | | |
| `billing_address.address_line1` | string | Yes | |
| `billing_address.address_line2` | string \| null | | |
| `billing_address.city` | string | Yes | |
| `billing_address.region_code` | string \| null | | Length: min 1. |
| `billing_address.postal_code` | string \| null | | |
| `billing_address.country_code` | string | Yes | |
| `billing_address.phone` | string \| null | | |
| `billing_address.sparklayer_id` | string \| null | | |
| `billing_address.first_name` | string \| null | | |
| `billing_address.last_name` | string \| null | | |
| `packages` | (Incoming \| Processing \| Shipment \| Cancelled \| Return)[] | Yes | Packages contained within this purchase |
| `packages[].identifiers` | object | | |
| `packages[].identifiers.sparklayer_package_id` | string (uuid) | Yes | A UUID for the package that must be unique within the purchase. You must generate this yourself |
| `packages[].identifiers.platform` | string \| null | | The identifier for the package on the e-commerce platform. Length: min 1. |
| `packages[].identifiers.internal` | string \| null | | The identifier for the package on your system. Length: min 1. |
| `packages[].identifiers.visible` | string \| null | | The identifier that will be shown to the customer in their recent orders |
| `packages[].accounting_files` | object[] | | |
| `packages[].accounting_files[].identifiers` | object | Yes | |
| `packages[].accounting_files[].identifiers.internal` | string \| null | | The identifier of the purchase file that is used by your system. Length: min 1. |
| `packages[].accounting_files[].identifiers.visible` | string \| null | | The identifier of the purchase file that should be shown to the customer. Default: `INV011`. |
| `packages[].accounting_files[].data` | object | Yes | |
| `packages[].accounting_files[].data.uri` | string (uri) \| null | | |
| `packages[].accounting_files[].data.type` | "uri" | Yes | Default: `uri`. |
| `packages[].accounting_files[].file_type` | "credit" \| "invoice" \| "payment" | Yes | |
| `packages[].line_items` | object[] | | |
| `packages[].line_items[].type` | "custom" \| "product" | | |
| `packages[].line_items[].identifiers` | object | Yes | |
| `packages[].line_items[].identifiers.sparklayer_item_key` | string \| null | | Internally used for tracking line items. For orders, can be set to null. Length: min 1. |
| `packages[].line_items[].identifiers.sparklayer_variant_id` | string \| null | | The ID of the variant on your e-commerce platform. Length: min 1. |
| `packages[].line_items[].identifiers.sku` | string \| null | | Length: max 128. |
| `packages[].line_items[].identifiers.platform` | string \| null | | The identifier for the product on the e-commerce platform. Length: min 1. |
| `packages[].line_items[].identifiers.internal` | string \| null | | The identifier for the product on your system. Length: min 1. |
| `packages[].line_items[].identifiers.visible` | string \| null | | A human-readable identifier for the product |
| `packages[].line_items[].name_parent` | string | Yes | Name of the product |
| `packages[].line_items[].name_child` | string \| null | | Name of the product variant/type |
| `packages[].line_items[].quantity` | number | Yes | |
| `packages[].line_items[].custom_attributes` | object[] | | |
| `packages[].line_items[].custom_attributes[].key` | string | Yes | Key or name of the attribute. |
| `packages[].line_items[].custom_attributes[].value` | string | Yes | Value of the attribute. |
| `packages[].line_items[].line_total` | object \| null | Yes | The total cost of this line. This is nullable only for quotes. |
| `packages[].line_items[].line_total.total_net` | object | Yes | The net cost of the line item. This should be the price after any discounts are applied |
| `packages[].line_items[].line_total.total_net.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].line_total.total_net.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].line_total.total_net_base` | object | | The net cost of the line item in the store's base currency. |
| `packages[].line_items[].line_total.total_net_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].line_total.total_net_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].line_total.total_tax` | object | | The tax on the line item. |
| `packages[].line_items[].line_total.total_tax.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].line_total.total_tax.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].line_total.total_tax_base` | object | | The tax on the line item in the store's base currency. |
| `packages[].line_items[].line_total.total_tax_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].line_total.total_tax_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].line_total.total_gross` | object | | The gross cost of the line item. |
| `packages[].line_items[].line_total.total_gross.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].line_total.total_gross.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].line_total.total_gross_base` | object | | The gross cost of the line item in the store's base currency. |
| `packages[].line_items[].line_total.total_gross_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].line_total.total_gross_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].line_total.discount_net` | object | Yes | The net discount that has already been applied to the total. This is just to show to the end user |
| `packages[].line_items[].line_total.discount_net.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].line_total.discount_net.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].line_total.discount_net_base` | object | | The net discount in the store's base currency. |
| `packages[].line_items[].line_total.discount_net_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].line_total.discount_net_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].line_total.tax_rate` | number (double) \| null | | **Deprecated.** The tax rate to apply to the net total. The value represents a percentage e.g. 20 means 20%. Default: `0`. Min 0. |
| `packages[].line_items[].tax_lines` | object[] | | |
| `packages[].line_items[].tax_lines[].title` | string | Yes | The title of the tax line |
| `packages[].line_items[].tax_lines[].amount` | object | Yes | The amount of tax of the tax line |
| `packages[].line_items[].tax_lines[].amount.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].tax_lines[].amount.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].tax_lines[].amount_base` | object | | The amount of tax of the tax line in the store's base currency |
| `packages[].line_items[].tax_lines[].amount_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].line_items[].tax_lines[].amount_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].line_items[].tax_lines[].rate` | number (double) \| null | Yes | The rate of the tax. The value represents a percentage e.g. 20 means 20%. Min 0. |
| `packages[].shipping_method` | object \| null | | Details of how the package was/will be shipped |
| `packages[].shipping_method.sku` | string \| null | | SKU that identifies the shipping method used. Length: min 1. |
| `packages[].shipping_method.name` | string | Yes | The friendly/human-readable name for the shipping method |
| `packages[].shipping_method.line_total` | object | Yes | Cost of the shipment |
| `packages[].shipping_method.line_total.total_net` | object | Yes | The net cost of the line item. This should be the price after any discounts are applied |
| `packages[].shipping_method.line_total.total_net.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.line_total.total_net.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.line_total.total_net_base` | object | | The net cost of the line item in the store's base currency. |
| `packages[].shipping_method.line_total.total_net_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.line_total.total_net_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.line_total.total_tax` | object | | The tax on the line item. |
| `packages[].shipping_method.line_total.total_tax.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.line_total.total_tax.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.line_total.total_tax_base` | object | | The tax on the line item in the store's base currency. |
| `packages[].shipping_method.line_total.total_tax_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.line_total.total_tax_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.line_total.total_gross` | object | | The gross cost of the line item. |
| `packages[].shipping_method.line_total.total_gross.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.line_total.total_gross.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.line_total.total_gross_base` | object | | The gross cost of the line item in the store's base currency. |
| `packages[].shipping_method.line_total.total_gross_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.line_total.total_gross_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.line_total.discount_net` | object | Yes | The net discount that has already been applied to the total. This is just to show to the end user |
| `packages[].shipping_method.line_total.discount_net.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.line_total.discount_net.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.line_total.discount_net_base` | object | | The net discount in the store's base currency. |
| `packages[].shipping_method.line_total.discount_net_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.line_total.discount_net_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.line_total.tax_rate` | number (double) \| null | | **Deprecated.** The tax rate to apply to the net total. The value represents a percentage e.g. 20 means 20%. Default: `0`. Min 0. |
| `packages[].shipping_method.tax_lines` | object[] | | |
| `packages[].shipping_method.tax_lines[].title` | string | Yes | The title of the tax line |
| `packages[].shipping_method.tax_lines[].amount` | object | Yes | The amount of tax of the tax line |
| `packages[].shipping_method.tax_lines[].amount.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.tax_lines[].amount.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.tax_lines[].amount_base` | object | | The amount of tax of the tax line in the store's base currency |
| `packages[].shipping_method.tax_lines[].amount_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `packages[].shipping_method.tax_lines[].amount_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `packages[].shipping_method.tax_lines[].rate` | number (double) \| null | Yes | The rate of the tax. The value represents a percentage e.g. 20 means 20%. Min 0. |
| `packages[].shipping_address` | object \| null | | |
| `packages[].shipping_address.name` | string \| null | | |
| `packages[].shipping_address.company` | string \| null | | |
| `packages[].shipping_address.address_line1` | string | Yes | |
| `packages[].shipping_address.address_line2` | string \| null | | |
| `packages[].shipping_address.city` | string | Yes | |
| `packages[].shipping_address.region_code` | string \| null | | Length: min 1. |
| `packages[].shipping_address.postal_code` | string \| null | | |
| `packages[].shipping_address.country_code` | string | Yes | |
| `packages[].shipping_address.phone` | string \| null | | |
| `packages[].shipping_address.sparklayer_id` | string \| null | | |
| `packages[].shipping_address.first_name` | string \| null | | |
| `packages[].shipping_address.last_name` | string \| null | | |
| `packages[].shipments` | object[] | | Carrier and tracking details for the shipment |
| `packages[].shipments[].carrier` | string | Yes | |
| `packages[].shipments[].carrier_id` | string | Yes | The tracking number/ID used by the carrier |
| `packages[].shipments[].tracking_url` | string (uri) \| null | | The URL the customer can use to track their shipment |
| `packages[].type` | "incoming" | | |
| `packages[].dates` | object | | |
| `packages[].dates.shipped_at` | string (date-time) | Yes | The date at which the package was shipped - include user timezone or Z for UTC (RFC-3339) |
| `accounting_files` | object[] | Yes | Any accounting files associated with this package e.g. invoices |
| `accounting_files[].identifiers` | object | Yes | |
| `accounting_files[].identifiers.internal` | string \| null | | The identifier of the purchase file that is used by your system. Length: min 1. |
| `accounting_files[].identifiers.visible` | string \| null | | The identifier of the purchase file that should be shown to the customer. Default: `INV011`. |
| `accounting_files[].data` | object | Yes | |
| `accounting_files[].data.uri` | string (uri) \| null | | |
| `accounting_files[].data.type` | "uri" | Yes | Default: `uri`. |
| `accounting_files[].file_type` | "credit" \| "invoice" \| "payment" | Yes | |
| `custom_fields` | object[] | Yes | Extra information for the purchase. This will be shown to the customer in their recent orders |
| `custom_fields[].name` | string | Yes | Name/identifier for the custom field. Length: min 1. |
| `custom_fields[].value` | string \| null | | Data for the custom field |
| `metadata` | object[] | | Extra information for the purchase. This not will be shown to the customer |
| `metadata[].name` | string | Yes | Name/identifier for the metadata. Length: min 1. |
| `metadata[].value` | string | Yes | Data for the metadata |

```json
{
  "type": "order",
  "purchase_identifiers": {
    "sparklayer": "63428136-658f-48a6-beb7-7f333dfd9686",
    "platform": "123456789",
    "internal": "<internal>",
    "visible": "B2B01123"
  },
  "customer_identifiers": {
    "sparklayer": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "sparklayer_impersonator": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "sparklayer_impersonator_assignee": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "sparklayer_child": "4217ba4f-7618-4e3b-b1af-9055639b18d1"
  },
  "company": {
    "id": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "section_id": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "section_name": "Bristol"
  },
  "payment_method": "quote",
  "dates": {
    "placed_at": "2020-01-01T00:00:00+02:00",
    "to_be_placed_at": "2020-01-01T00:00:00+02:00",
    "payment_due_at": "2020-01-01T00:00:00+02:00"
  },
  "customer_reference": "Please deliver to the back of the store",
  "po_number": "PO-001",
  "shipping_requested_date": "2020-01-01T00:00:00+02:00",
  "recurring_purchase": {
    "template_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "cancelled_at": "2020-01-01T00:00:00+02:00",
    "to_be_placed_at_initial": "2020-01-01T00:00:00+02:00"
  },
  "currency_code": "GBP",
  "currency_code_base": "GBP",
  "calculated_total": {
    "number": "15.99",
    "currency": "GBP"
  },
  "calculated_total_usd": {
    "number": "15.99",
    "currency": "GBP"
  },
  "calculated_total_base": {
    "number": "15.99",
    "currency": "GBP"
  },
  "quote": {
    "status_slug": "<status_slug>",
    "status": {
      "id": "<id>",
      "name": "<name>",
      "slug": "<slug>",
      "default": true,
      "next": "<next>",
      "actions": [
        "edit_quote"
      ],
      "created_at": "2026-01-31T09:00:00Z",
      "updated_at": "2026-01-31T09:00:00Z",
      "deleted_at": "2026-01-31T09:00:00Z"
    },
    "expiry": "2020-01-01T00:00:00+02:00"
  },
  "payment_status": "unpaid",
  "total_paid": {
    "number": "15.99",
    "currency": "GBP"
  },
  "revision_date": "2020-01-01T00:00:00+02:00",
  "tax_lines": [
    {
      "title": "HST",
      "amount": {
        "number": "15.99",
        "currency": "GBP"
      },
      "amount_base": {
        "number": "15.99",
        "currency": "GBP"
      },
      "rate": 20
    }
  ],
  "billing_address": {
    "name": "Tom Jones",
    "company": "Tom Jones Hardware Ltd",
    "address_line1": "7 Philosophy way",
    "address_line2": null,
    "city": "Willerby",
    "region_code": null,
    "postal_code": "BJ6 9MK",
    "country_code": "GB",
    "phone": "0123456789",
    "sparklayer_id": "63428136-658f-48a6-beb7-7f333dfd9686",
    "first_name": "Tom",
    "last_name": "Jones"
  },
  "packages": [
    {
      "identifiers": {
        "sparklayer_package_id": "63428136-658f-48a6-beb7-7f333dfd9686",
        "platform": "123456789",
        "internal": "<internal>",
        "visible": "<visible>"
      },
      "accounting_files": [
        {
          "identifiers": {
            "internal": "INV011",
            "visible": "INV011"
          },
          "data": {
            "uri": "https://example.com",
            "type": "uri"
          },
          "file_type": "invoice"
        }
      ],
      "line_items": [
        {
          "type": "custom",
          "identifiers": {
            "sparklayer_item_key": "<sparklayer_item_key>",
            "sparklayer_variant_id": "45552423353839",
            "sku": "CAT-MUG",
            "platform": "123456789",
            "internal": "<internal>",
            "visible": "<visible>"
          },
          "name_parent": "T-Shirt",
          "name_child": "Red",
          "quantity": 4,
          "custom_attributes": [
            {
              "key": "mug text",
              "value": "best company ever"
            }
          ],
          "line_total": {
            "total_net": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_net_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_tax": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_tax_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_gross": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_gross_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "discount_net": {
              "number": "15.99",
              "currency": "GBP"
            },
            "discount_net_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "tax_rate": 20
          },
          "tax_lines": [
            {
              "title": "HST",
              "amount": {
                "number": "15.99",
                "currency": "GBP"
              },
              "amount_base": {
                "number": "15.99",
                "currency": "GBP"
              },
              "rate": 20
            }
          ]
        }
      ],
      "shipping_method": {
        "sku": "SHIP-ECO",
        "name": "Standard Shipping",
        "line_total": {
          "total_net": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_net_base": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_tax": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_tax_base": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_gross": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_gross_base": {
            "number": "15.99",
            "currency": "GBP"
          },
          "discount_net": {
            "number": "15.99",
            "currency": "GBP"
          },
          "discount_net_base": {
            "number": "15.99",
            "currency": "GBP"
          },
          "tax_rate": 20
        },
        "tax_lines": [
          {
            "title": "HST",
            "amount": {
              "number": "15.99",
              "currency": "GBP"
            },
            "amount_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "rate": 20
          }
        ]
      },
      "shipping_address": {
        "name": "Tom Jones",
        "company": "Tom Jones Hardware Ltd",
        "address_line1": "7 Philosophy way",
        "address_line2": null,
        "city": "Willerby",
        "region_code": null,
        "postal_code": "BJ6 9MK",
        "country_code": "GB",
        "phone": "0123456789",
        "sparklayer_id": "63428136-658f-48a6-beb7-7f333dfd9686",
        "first_name": "Tom",
        "last_name": "Jones"
      },
      "shipments": [
        {
          "carrier": "Carrier Company Ltd",
          "carrier_id": "<carrier_id>",
          "tracking_url": "https://example.com"
        }
      ],
      "type": "incoming"
    }
  ],
  "accounting_files": [
    {
      "identifiers": {
        "internal": "INV011",
        "visible": "INV011"
      },
      "data": {
        "uri": "https://example.com",
        "type": "uri"
      },
      "file_type": "invoice"
    }
  ],
  "custom_fields": [
    {
      "name": "delivery-date",
      "value": "2023-10-28"
    }
  ],
  "metadata": [
    {
      "name": "example-key",
      "value": "1234"
    }
  ]
}
```

### Responses

#### 200: The created or updated purchase.

The `Purchase` object: the request body's fields, plus:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `dates.created_at` | string (date-time) | | The date the purchase was created in SparkLayer (RFC-3339). This is read only - it should not be sent to the API, but will be returned form it |
| `dates.updated_at` | string (date-time) | | The date the purchase was last updated in SparkLayer (RFC-3339). This is read only - it should not be sent to the API, but will be returned form it |
| `dates.calculated_submitted_at` | string (date-time) | | The date the purchase was submitted (RFC-3339). This is when the cart is converted into another purchase type. This is read only - it should not be sent to the API, but will be returned form it |
| `dates.expires_at` | string (date-time) | | the date at which the purchase will expire and become archived (RFC-3339). This is read only - it should not be sent to the API, but will be returned form it |
| `calculated_shipping_address` | string \| null | | A single string containing all the details of the shipping address. This is read only - it should not be sent to the API, but will be returned form it |
| `calculated_fulfilment_status` | "incoming" \| "processing" \| "shipped" \| "part_shipped" \| "cancelled" \| "returned" \| "part_returned" \| "varied" \| null | | The status of the order, calculated from the statuses of the individual packages. This is read only - it should not be sent to the API, but will be returned form it |

```json
{
  "type": "order",
  "purchase_identifiers": {
    "sparklayer": "63428136-658f-48a6-beb7-7f333dfd9686",
    "platform": "123456789",
    "internal": "<internal>",
    "visible": "B2B01123"
  },
  "customer_identifiers": {
    "sparklayer": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "sparklayer_impersonator": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "sparklayer_impersonator_assignee": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "sparklayer_child": "4217ba4f-7618-4e3b-b1af-9055639b18d1"
  },
  "company": {
    "id": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "section_id": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "section_name": "Bristol"
  },
  "payment_method": "quote",
  "dates": {
    "created_at": "2020-01-01T00:00:00+02:00",
    "updated_at": "2020-01-01T00:00:00+02:00",
    "placed_at": "2020-01-01T00:00:00+02:00",
    "to_be_placed_at": "2020-01-01T00:00:00+02:00",
    "calculated_submitted_at": "2020-01-01T00:00:00+02:00",
    "expires_at": "2020-01-01T00:00:00+02:00",
    "payment_due_at": "2020-01-01T00:00:00+02:00"
  },
  "customer_reference": "Please deliver to the back of the store",
  "po_number": "PO-001",
  "shipping_requested_date": "2020-01-01T00:00:00+02:00",
  "recurring_purchase": {
    "template_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "cancelled_at": "2020-01-01T00:00:00+02:00",
    "to_be_placed_at_initial": "2020-01-01T00:00:00+02:00"
  },
  "currency_code": "GBP",
  "calculated_shipping_address": "John Spark, SparkLayer, SparkLayer HQ, Example City, 12345",
  "calculated_total": {
    "number": "15.99",
    "currency": "GBP"
  },
  "calculated_total_usd": {
    "number": "15.99",
    "currency": "GBP"
  },
  "calculated_total_base": {
    "number": "15.99",
    "currency": "GBP"
  },
  "calculated_fulfilment_status": "processing",
  "quote": {
    "status_slug": "<status_slug>",
    "status": {
      "id": "<id>",
      "name": "<name>",
      "slug": "<slug>",
      "default": true,
      "next": "<next>",
      "actions": [
        "edit_quote"
      ],
      "created_at": "2026-01-31T09:00:00Z",
      "updated_at": "2026-01-31T09:00:00Z",
      "deleted_at": "2026-01-31T09:00:00Z"
    },
    "expiry": "2020-01-01T00:00:00+02:00"
  },
  "payment_status": "unpaid",
  "total_paid": {
    "number": "15.99",
    "currency": "GBP"
  },
  "revision_date": "2020-01-01T00:00:00+02:00",
  "tax_lines": [
    {
      "title": "HST",
      "amount": {
        "number": "15.99",
        "currency": "GBP"
      },
      "amount_base": {
        "number": "15.99",
        "currency": "GBP"
      },
      "rate": 20
    }
  ],
  "billing_address": {
    "name": "Tom Jones",
    "company": "Tom Jones Hardware Ltd",
    "address_line1": "7 Philosophy way",
    "address_line2": null,
    "city": "Willerby",
    "region_code": null,
    "postal_code": "BJ6 9MK",
    "country_code": "GB",
    "phone": "0123456789",
    "sparklayer_id": "63428136-658f-48a6-beb7-7f333dfd9686",
    "first_name": "Tom",
    "last_name": "Jones"
  },
  "packages": [
    {
      "identifiers": {
        "sparklayer_package_id": "63428136-658f-48a6-beb7-7f333dfd9686",
        "platform": "123456789",
        "internal": "<internal>",
        "visible": "<visible>"
      },
      "accounting_files": [
        {
          "identifiers": {
            "internal": "INV011",
            "visible": "INV011"
          },
          "data": {
            "uri": "https://example.com",
            "type": "uri"
          },
          "file_type": "invoice"
        }
      ],
      "line_items": [
        {
          "type": "custom",
          "identifiers": {
            "sparklayer_item_key": "<sparklayer_item_key>",
            "sparklayer_variant_id": "45552423353839",
            "sku": "CAT-MUG",
            "platform": "123456789",
            "internal": "<internal>",
            "visible": "<visible>"
          },
          "name_parent": "T-Shirt",
          "name_child": "Red",
          "quantity": 4,
          "custom_attributes": [
            {
              "key": "mug text",
              "value": "best company ever"
            }
          ],
          "line_total": {
            "total_net": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_net_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_tax": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_tax_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_gross": {
              "number": "15.99",
              "currency": "GBP"
            },
            "total_gross_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "discount_net": {
              "number": "15.99",
              "currency": "GBP"
            },
            "discount_net_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "tax_rate": 20
          },
          "tax_lines": [
            {
              "title": "HST",
              "amount": {
                "number": "15.99",
                "currency": "GBP"
              },
              "amount_base": {
                "number": "15.99",
                "currency": "GBP"
              },
              "rate": 20
            }
          ]
        }
      ],
      "shipping_method": {
        "sku": "SHIP-ECO",
        "name": "Standard Shipping",
        "line_total": {
          "total_net": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_net_base": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_tax": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_tax_base": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_gross": {
            "number": "15.99",
            "currency": "GBP"
          },
          "total_gross_base": {
            "number": "15.99",
            "currency": "GBP"
          },
          "discount_net": {
            "number": "15.99",
            "currency": "GBP"
          },
          "discount_net_base": {
            "number": "15.99",
            "currency": "GBP"
          },
          "tax_rate": 20
        },
        "tax_lines": [
          {
            "title": "HST",
            "amount": {
              "number": "15.99",
              "currency": "GBP"
            },
            "amount_base": {
              "number": "15.99",
              "currency": "GBP"
            },
            "rate": 20
          }
        ]
      },
      "shipping_address": {
        "name": "Tom Jones",
        "company": "Tom Jones Hardware Ltd",
        "address_line1": "7 Philosophy way",
        "address_line2": null,
        "city": "Willerby",
        "region_code": null,
        "postal_code": "BJ6 9MK",
        "country_code": "GB",
        "phone": "0123456789",
        "sparklayer_id": "63428136-658f-48a6-beb7-7f333dfd9686",
        "first_name": "Tom",
        "last_name": "Jones"
      },
      "shipments": [
        {
          "carrier": "Carrier Company Ltd",
          "carrier_id": "<carrier_id>",
          "tracking_url": "https://example.com"
        }
      ],
      "type": "incoming"
    }
  ],
  "accounting_files": [
    {
      "identifiers": {
        "internal": "INV011",
        "visible": "INV011"
      },
      "data": {
        "uri": "https://example.com",
        "type": "uri"
      },
      "file_type": "invoice"
    }
  ],
  "custom_fields": [
    {
      "name": "delivery-date",
      "value": "2023-10-28"
    }
  ],
  "metadata": [
    {
      "name": "example-key",
      "value": "1234"
    }
  ]
}
```

#### 403: Trying to update purchase SparkLayer ID, which is immutable

`application/problem+json`: the standard error body (below).

#### 404: Not found.

`application/problem+json`: the standard error body (below).

#### 409: A conflict has occurred

`application/problem+json`: the standard error body (below).

#### 500: An unexpected error.

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |
| `errors` | object[] | | |
| `errors[].code` | string | | A machine-readable error message |
| `errors[].property` | string | | The offending property |
| `errors[].message` | string | | A human-readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://hub.sparklayer.io/tech-docs",
  "errors": [
    {
      "code": "unique-constraint-violation",
      "property": "purchase_identifiers.sparklayer",
      "message": "Each stock level must have a unique stock location and sku combination"
    }
  ]
}
```


---

# Delete a purchase

URL: https://docs.sparklayer.io/developers/api/purchasing/delete-purchase
Operation: `DELETE /api/v1/purchases/{lookupBy}/{identifier}` (operationId `deletePurchase`)
OpenAPI spec: https://docs.sparklayer.io/openapi/purchasing.yaml

Deletes the purchase that matches `lookupBy` and `identifier`, and returns `204`. Returns `404` if no purchase matches.

`DELETE /api/v1/purchases/{lookupBy}/{identifier}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X DELETE "https://app.sparklayer.io/api/v1/purchases/platform/123456789" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `lookupBy` | "sparklayer" \| "platform" \| "internal" \| "visible" | Yes | Which of the purchase's `purchase_identifiers` `identifier` is: `sparklayer`, `platform`, `internal` or `visible`. Example: `platform` |
| `identifier` | string \| string (uuid) | Yes | The purchase identifier, of the kind set by `lookupBy`. With `lookupBy=sparklayer` it must be a UUID. Example: `123456789` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Length: min 1. Example: `jones-climbing` |

### Responses

#### 204: The purchase was deleted. No body.

#### 404: Not found.

`application/problem+json`: the standard error body (below).

#### 500: An unexpected error.

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |
| `errors` | object[] | | |
| `errors[].code` | string | | A machine-readable error message |
| `errors[].property` | string | | The offending property |
| `errors[].message` | string | | A human-readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://hub.sparklayer.io/tech-docs",
  "errors": [
    {
      "code": "unique-constraint-violation",
      "property": "purchase_identifiers.sparklayer",
      "message": "Each stock level must have a unique stock location and sku combination"
    }
  ]
}
```


---

# List purchases

URL: https://docs.sparklayer.io/developers/api/purchasing/get-purchases
Operation: `GET /api/v1/purchases` (operationId `getPurchases`)
OpenAPI spec: https://docs.sparklayer.io/openapi/purchasing.yaml

Lists purchases, filtered by customer, company, status, type, quote status, search term and date ranges. Results are sorted by `order_by`, newest first when you don't set it. Page through them with `limit` (up to 500) and `offset`, and stop when a page has fewer than `limit` results.

`GET /api/v1/purchases`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/purchases" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | | Limit the number of results returned. Min 1, max 500. |
| `offset` | integer | | Skip this many results, for paging. Sorted by order_by, newest first when none is given. Min 0. |
| `order_by` | "created_at" \| "updated_at" \| "placed_at" \| "calculated_submitted_at" \| "shipping_requested_date" | | The date field to sort by, in descending order (newest first). Without it, results are newest first. |
| `customer_identifiers[sparklayer]` | string | | Filter by customer_identifiers[sparklayer]. Accepts comma-separated values. Maximum total length of all values is 2000 characters. Length: min 1, max 2000. |
| `customer_identifiers[sparklayer_impersonator]` | string | | Filter by customer_identifiers[sparklayer_impersonator]. Accepts comma-separated values. Maximum total length of all values is 2000 characters. Length: min 1, max 2000. |
| `customer_identifiers[sparklayer_sales_rep]` | string | | Filter by customer_identifiers[sparklayer_sales_rep]. Accepts comma-separated values. Maximum total length of all values is 2000 characters. Length: min 1, max 2000. |
| `customer_identifiers[sparklayer_impersonator_assignee]` | string | | Filter by customer_identifiers[sparklayer_impersonator_assignee]. Accepts comma-separated values. Maximum total length of all values is 2000 characters. To get purchases that have no assignee, include a string value of 'NULL'. Length: min 1, max 2000. |
| `company[id]` | string | | Filter by company[id]. Accepts comma-separated values. Maximum total length of all values is 2000 characters. Use this rather than listing every section id to report on a whole company. Length: min 1, max 2000. |
| `company[section_id]` | string | | Filter by company[section_id]. Accepts comma-separated values. Maximum total length of all values is 2000 characters. Length: min 1, max 2000. |
| `status` | "incoming" \| "processing" \| "shipped" \| "part_shipped" \| "cancelled" \| "returned" \| "part_returned" \| "varied" | | Only purchases with this status. Example: `shipped` |
| `type` | "order" \| "quote" \| "cart" \| "awaiting_approval" \| "awaiting_merchant" \| "archived" \| "platform_archived" \| "pending_recurring_order" | | Only purchases of this type. Example: `order` |
| `quote_status` | string | | Only quotes with this quote status slug. Example: `quote-requested` |
| `search` | string | | Only purchases that match this search term. Example: `PO-12345` |
| `dates[last_updated][lte]` | string | | Only purchases last updated on or before this date. Length: min 1. |
| `dates[last_updated][gte]` | string | | Only purchases last updated on or after this date. Length: min 1. |
| `dates[placed][lte]` | string | | Only purchases placed on or before this date. Length: min 1. |
| `dates[placed][gte]` | string | | Only purchases placed on or after this date. Length: min 1. |
| `dates[submitted][lte]` | string | | Only purchases submitted on or before this date. Length: min 1. |
| `dates[submitted][gte]` | string | | Only purchases submitted on or after this date. Length: min 1. |
| `dates[shipping_requested][lte]` | string | | Only purchases with a requested shipping date on or before this date. Length: min 1. |
| `dates[shipping_requested][gte]` | string | | Only purchases with a requested shipping date on or after this date. Length: min 1. |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Length: min 1. Example: `jones-climbing` |

### Responses

#### 200: The matching purchases.

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].type` | "quote" \| "cart" \| "awaiting_approval" \| "order" \| "awaiting_merchant" \| "archived" \| "platform_archived" \| "pending_recurring_order" | Yes | |
| `[].purchase_identifiers` | object | Yes | |
| `[].purchase_identifiers.sparklayer` | string (uuid) \| null | | The identifier SparkLayer uses for the purchase. You will need to generate this if the purchase does not exist. Length: min 1. |
| `[].purchase_identifiers.platform` | string \| null | | The identifier for the purchase on the e-commerce platform. Length: min 1. |
| `[].purchase_identifiers.internal` | string \| null | | The identifier for the purchase on your system. Length: min 1. |
| `[].purchase_identifiers.visible` | string \| null | | The identifier that will be shown to the customer in their recent orders |
| `[].customer_identifiers` | object | Yes | |
| `[].customer_identifiers.sparklayer` | string | Yes | The ID of the customer that that order is for. |
| `[].customer_identifiers.sparklayer_impersonator` | string \| null | | The ID of the sales agent placing the order. |
| `[].customer_identifiers.sparklayer_impersonator_assignee` | string \| null | | The ID of the sales agent assigned to be responsible for the order. |
| `[].customer_identifiers.sparklayer_child` | string \| null | | The ID of the company user that placed the order. |
| `[].company` | object \| null | | Company sections are opt-in; omit this entirely for merchants that do not use them. |
| `[].company.id` | string (uuid) \| null | | The ID of the company the purchase was placed for. |
| `[].company.section_id` | string (uuid) \| null | | The ID of the company section the purchase was placed for. |
| `[].company.section_name` | string \| null | | The section name at the time of purchase, kept so historical purchases stay readable after a section is renamed or deleted. Not filterable. Length: max 128. |
| `[].payment_method` | "quote" \| "upfrontPayment" \| "paymentOnAccount" \| "paymentByInvoice" \| null | | How the purchase was/will be paid for |
| `[].dates` | object | Yes | |
| `[].dates.created_at` | string (date-time) | | The date the purchase was created in SparkLayer (RFC-3339). This is read only - it should not be sent to the API, but will be returned form it |
| `[].dates.updated_at` | string (date-time) | | The date the purchase was last updated in SparkLayer (RFC-3339). This is read only - it should not be sent to the API, but will be returned form it |
| `[].dates.placed_at` | string (date-time) \| null | | The date at which the purchase was placed - include user timezone or Z for UTC (RFC-3339) |
| `[].dates.to_be_placed_at` | string (date-time) \| null | | The date at which the purchase is due to be placed, for a purchase that is scheduled rather than placed immediately (RFC-3339). It can be changed while the purchase is still pending |
| `[].dates.calculated_submitted_at` | string (date-time) | | The date the purchase was submitted (RFC-3339). This is when the cart is converted into another purchase type. This is read only - it should not be sent to the API, but will be returned form it |
| `[].dates.expires_at` | string (date-time) | | the date at which the purchase will expire and become archived (RFC-3339). This is read only - it should not be sent to the API, but will be returned form it |
| `[].dates.payment_due_at` | string (date-time) | | The date at which payment for the purchase is expected |
| `[].customer_reference` | string \| null | | Additional information that a customer adds to the order |
| `[].po_number` | string \| null | | PO number for the purchase |
| `[].shipping_requested_date` | string (date-time) \| null | | The date requested for the delivery to arrive |
| `[].recurring_purchase` | object \| null | | Present only for a purchase created from a recurring purchase template. Both properties are stored when the purchase is created and ignored on any later update |
| `[].recurring_purchase.template_id` | string (uuid) \| null | | The recurring purchase template this purchase was created from. Set on creation and ignored on update |
| `[].recurring_purchase.cancelled_at` | string (date-time) \| null | | The date the customer cancelled the purchase, after which it will not be placed (RFC-3339). Cancelling does not free the date - the template has already had its turn for it |
| `[].recurring_purchase.to_be_placed_at_initial` | string (date-time) \| null | | The date to_be_placed_at was first set to (RFC-3339). Set on creation and ignored on update, so that rescheduling cannot let the same template produce a second purchase for the same date |
| `[].currency_code` | string \| null | | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `[].calculated_shipping_address` | string \| null | | A single string containing all the details of the shipping address. This is read only - it should not be sent to the API, but will be returned form it |
| `[].calculated_total` | object | | Gross total price of the purchase, calculated by SparkLayer based on package and shipment costs. This is read only - it should not be sent to the API, but will be returned form it |
| `[].calculated_total.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `[].calculated_total.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `[].calculated_total_usd` | object | | Gross total price in USD of the purchase, calculated by SparkLayer based on package and shipment costs. This is read only - it should not be sent to the API, but will be returned form it |
| `[].calculated_total_usd.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `[].calculated_total_usd.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `[].calculated_total_base` | object | | Gross total price in the store's base currency, calculated by SparkLayer. This is read only - it should not be sent to the API, but will be returned from it |
| `[].calculated_total_base.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `[].calculated_total_base.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |
| `[].calculated_fulfilment_status` | "incoming" \| "processing" \| "shipped" \| "part_shipped" \| "cancelled" \| "returned" \| "part_returned" \| "varied" \| null | | The status of the order, calculated from the statuses of the individual packages. This is read only - it should not be sent to the API, but will be returned form it |
| `[].quote` | object \| null | | Quote data |
| `[].quote.status_slug` | string | | The slug of the quote status applied to this quote |
| `[].quote.status` | object \| null | | |
| `[].quote.status.id` | string | | |
| `[].quote.status.name` | string | | Length: max 45. |
| `[].quote.status.slug` | string | | Length: max 45. Pattern: `^[a-z0-9-]+$`. |
| `[].quote.status.default` | boolean | | |
| `[].quote.status.next` | string \| null | | Length: max 45. Pattern: `^[a-z0-9-]+$`. |
| `[].quote.status.actions` | ("edit_quote" \| "complete_quote" \| "expiry_date" \| "download_pdf")[] | | |
| `[].quote.status.created_at` | string (date-time) | | |
| `[].quote.status.updated_at` | string (date-time) | | |
| `[].quote.status.deleted_at` | string (date-time) \| null | | |
| `[].quote.expiry` | string (date-time) \| null | | The date at which the quote is considered expired and no longer valid (RFC-3339) |
| `[].payment_status` | "unpaid" \| "part_paid" \| "paid" | | That payment status of the order |
| `[].total_paid` | object | | |
| `[].total_paid.number` | string | Yes | The amount of currency in this currency, represented as a string. Length: min 1. |
| `[].total_paid.currency` | string | Yes | The 3 letter currency code used for the prices in the purchase. Length: min 3, max 3. |

```json
[
  {
    "type": "order",
    "purchase_identifiers": {
      "sparklayer": "63428136-658f-48a6-beb7-7f333dfd9686",
      "platform": "123456789",
      "internal": "<internal>",
      "visible": "B2B01123"
    },
    "customer_identifiers": {
      "sparklayer": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
      "sparklayer_impersonator": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
      "sparklayer_impersonator_assignee": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
      "sparklayer_child": "4217ba4f-7618-4e3b-b1af-9055639b18d1"
    },
    "company": {
      "id": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
      "section_id": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
      "section_name": "Bristol"
    },
    "payment_method": "quote",
    "dates": {
      "created_at": "2020-01-01T00:00:00+02:00",
      "updated_at": "2020-01-01T00:00:00+02:00",
      "placed_at": "2020-01-01T00:00:00+02:00",
      "to_be_placed_at": "2020-01-01T00:00:00+02:00",
      "calculated_submitted_at": "2020-01-01T00:00:00+02:00",
      "expires_at": "2020-01-01T00:00:00+02:00",
      "payment_due_at": "2020-01-01T00:00:00+02:00"
    },
    "customer_reference": "Please deliver to the back of the store",
    "po_number": "PO-001",
    "shipping_requested_date": "2020-01-01T00:00:00+02:00",
    "recurring_purchase": {
      "template_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "cancelled_at": "2020-01-01T00:00:00+02:00",
      "to_be_placed_at_initial": "2020-01-01T00:00:00+02:00"
    },
    "currency_code": "GBP",
    "calculated_shipping_address": "John Spark, SparkLayer, SparkLayer HQ, Example City, 12345",
    "calculated_total": {
      "number": "15.99",
      "currency": "GBP"
    },
    "calculated_total_usd": {
      "number": "15.99",
      "currency": "GBP"
    },
    "calculated_total_base": {
      "number": "15.99",
      "currency": "GBP"
    },
    "calculated_fulfilment_status": "processing",
    "quote": {
      "status_slug": "<status_slug>",
      "status": {
        "id": "<id>",
        "name": "<name>",
        "slug": "<slug>",
        "default": true,
        "next": "<next>",
        "actions": [
          "edit_quote"
        ],
        "created_at": "2026-01-31T09:00:00Z",
        "updated_at": "2026-01-31T09:00:00Z",
        "deleted_at": "2026-01-31T09:00:00Z"
      },
      "expiry": "2020-01-01T00:00:00+02:00"
    },
    "payment_status": "unpaid",
    "total_paid": {
      "number": "15.99",
      "currency": "GBP"
    }
  }
]
```

#### 500: An unexpected error.

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |
| `errors` | object[] | | |
| `errors[].code` | string | | A machine-readable error message |
| `errors[].property` | string | | The offending property |
| `errors[].message` | string | | A human-readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://hub.sparklayer.io/tech-docs",
  "errors": [
    {
      "code": "unique-constraint-violation",
      "property": "purchase_identifiers.sparklayer",
      "message": "Each stock level must have a unique stock location and sku combination"
    }
  ]
}
```


---

# List purchase history

URL: https://docs.sparklayer.io/developers/api/purchasing/get-purchase-history
Operation: `GET /api/v1/purchases/{lookupBy}/{identifier}/history` (operationId `getPurchaseHistory`)
OpenAPI spec: https://docs.sparklayer.io/openapi/purchasing.yaml

Returns the history of the purchase that matches `lookupBy` and `identifier`: its message, note, email and update events. Returns `404` if no purchase matches.

`GET /api/v1/purchases/{lookupBy}/{identifier}/history`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/purchases/platform/123456789/history" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `lookupBy` | "sparklayer" \| "platform" \| "internal" \| "visible" | Yes | Which of the purchase's `purchase_identifiers` `identifier` is: `sparklayer`, `platform`, `internal` or `visible`. Example: `platform` |
| `identifier` | string | Yes | The purchase identifier, of the kind set by `lookupBy`. With `lookupBy=sparklayer` it must be a UUID. Length: min 1. Example: `123456789` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Length: min 1. Example: `jones-climbing` |

### Responses

#### 200: The purchase's history events.

An array. Each item is one of these (or a combination):

**MessageEvent**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].created_at` | string (date-time) | Yes | date and time of the event |
| `[].event_type` | "message" \| "note" | Yes | |
| `[].created_by` | string \| null | Yes | The ID of the actor (customer, sales agent..) that created the message. |
| `[].body` | string | Yes | Length: max 2047. |

**EmailEvent**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].created_at` | string (date-time) | Yes | date and time of the event |
| `[].event_type` | "email" | Yes | |
| `[].sent_by` | string \| null | Yes | An identity for the sender of the email creating the notification |
| `[].body` | string | Yes | Length: max 2047. |

**UpdateEvent**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].created_at` | string (date-time) | Yes | date and time of the event |
| `[].event_type` | "update" | | |
| `[].purchase_type` | "quote" | | |
| `[].fields` | (AssigneeChangeEvent \| ExpiryChangeEvent \| StatusChangeEvent)[] | | |
| `[].fields[].created_at` | string (date-time) | | date and time of the event |
| `[].fields[].field` | "assignee" | | |
| `[].fields[].old_value` | string \| null | | previous assignee |
| `[].fields[].new_value` | string \| null | | new assignee |
| `[].fields[].created_by` | string \| null | | The ID of the actor (customer, sales agent..) that made the edit. |
| `[].fields[].purchase_type` | "quote" | | |

```json
[
  {
    "created_at": "2020-01-01T00:00:00+02:00",
    "event_type": "message",
    "created_by": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "body": "<body>"
  }
]
```

#### 404: Not found.

`application/problem+json`: the standard error body (below).

#### 500: An unexpected error.

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |
| `errors` | object[] | | |
| `errors[].code` | string | | A machine-readable error message |
| `errors[].property` | string | | The offending property |
| `errors[].message` | string | | A human-readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://hub.sparklayer.io/tech-docs",
  "errors": [
    {
      "code": "unique-constraint-violation",
      "property": "purchase_identifiers.sparklayer",
      "message": "Each stock level must have a unique stock location and sku combination"
    }
  ]
}
```


---

# Create a purchase history entry

URL: https://docs.sparklayer.io/developers/api/purchasing/create-a-purchase-history-entry
Operation: `POST /api/v1/purchases/{lookupBy}/{identifier}/history` (operationId `createPurchaseHistory`)
OpenAPI spec: https://docs.sparklayer.io/openapi/purchasing.yaml

Adds an event to the history of the purchase that matches `lookupBy` and `identifier`. Set `event_type` to `message` or `note` (with `created_by` and `body`), or to `email` (with `sent_by` and `body`). Returns `404` if no purchase matches.

`POST /api/v1/purchases/{lookupBy}/{identifier}/history`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/purchases/platform/123456789/history" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "event_type": "message",
  "created_by": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
  "body": "<body>"
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `lookupBy` | "sparklayer" \| "platform" \| "internal" \| "visible" | Yes | Which of the purchase's `purchase_identifiers` `identifier` is: `sparklayer`, `platform`, `internal` or `visible`. Example: `platform` |
| `identifier` | string | Yes | The purchase identifier, of the kind set by `lookupBy`. With `lookupBy=sparklayer` it must be a UUID. Length: min 1. Example: `123456789` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Length: min 1. Example: `jones-climbing` |

### Request body (`application/json`) (required)

One of these:

**MessageEventBase**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `event_type` | "message" \| "note" | Yes | |
| `created_by` | string \| null | Yes | The ID of the actor (customer, sales agent..) that created the message. |
| `body` | string | Yes | Length: max 2047. |

**EmailEventBase**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `event_type` | "email" | Yes | |
| `sent_by` | string \| null | Yes | An identity for the sender of the email creating the notification |
| `body` | string | Yes | Length: max 2047. |

```json
{
  "event_type": "message",
  "created_by": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
  "body": "<body>"
}
```

### Responses

#### 200: The purchase's history events.

An array. Each item is one of these (or a combination):

**MessageEvent**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].created_at` | string (date-time) | Yes | date and time of the event |
| `[].event_type` | "message" \| "note" | Yes | |
| `[].created_by` | string \| null | Yes | The ID of the actor (customer, sales agent..) that created the message. |
| `[].body` | string | Yes | Length: max 2047. |

**EmailEvent**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].created_at` | string (date-time) | Yes | date and time of the event |
| `[].event_type` | "email" | Yes | |
| `[].sent_by` | string \| null | Yes | An identity for the sender of the email creating the notification |
| `[].body` | string | Yes | Length: max 2047. |

**UpdateEvent**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].created_at` | string (date-time) | Yes | date and time of the event |
| `[].event_type` | "update" | | |
| `[].purchase_type` | "quote" | | |
| `[].fields` | (AssigneeChangeEvent \| ExpiryChangeEvent \| StatusChangeEvent)[] | | |
| `[].fields[].created_at` | string (date-time) | | date and time of the event |
| `[].fields[].field` | "assignee" | | |
| `[].fields[].old_value` | string \| null | | previous assignee |
| `[].fields[].new_value` | string \| null | | new assignee |
| `[].fields[].created_by` | string \| null | | The ID of the actor (customer, sales agent..) that made the edit. |
| `[].fields[].purchase_type` | "quote" | | |

```json
[
  {
    "created_at": "2020-01-01T00:00:00+02:00",
    "event_type": "message",
    "created_by": "4217ba4f-7618-4e3b-b1af-9055639b18d1",
    "body": "<body>"
  }
]
```

#### 404: Not found.

`application/problem+json`: the standard error body (below).

#### 500: An unexpected error.

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |
| `errors` | object[] | | |
| `errors[].code` | string | | A machine-readable error message |
| `errors[].property` | string | | The offending property |
| `errors[].message` | string | | A human-readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://hub.sparklayer.io/tech-docs",
  "errors": [
    {
      "code": "unique-constraint-violation",
      "property": "purchase_identifiers.sparklayer",
      "message": "Each stock level must have a unique stock location and sku combination"
    }
  ]
}
```


---

# List purchase transactions

URL: https://docs.sparklayer.io/developers/api/purchasing/get-purchase-transactions
Operation: `GET /api/v1/purchases/{lookupBy}/{identifier}/transactions` (operationId `getTransactions`)
OpenAPI spec: https://docs.sparklayer.io/openapi/purchasing.yaml

Returns the transactions, such as payments and refunds, recorded against the purchase that matches `lookupBy` and `identifier`, including those stored for information only. Returns `404` if no purchase matches.

`GET /api/v1/purchases/{lookupBy}/{identifier}/transactions`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/purchases/platform/123456789/transactions" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `lookupBy` | "sparklayer" \| "platform" \| "internal" \| "visible" | Yes | Which of the purchase's `purchase_identifiers` `identifier` is: `sparklayer`, `platform`, `internal` or `visible`. Example: `platform` |
| `identifier` | string \| string (uuid) | Yes | The purchase identifier, of the kind set by `lookupBy`. With `lookupBy=sparklayer` it must be a UUID. Example: `123456789` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Length: min 1. Example: `jones-climbing` |

### Responses

#### 200: The transactions recorded against the purchase.

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].id` | string (uuid) \| null | | The identifier SparkLayer uses for the transaction. Length: min 1. |
| `[].purchase_spark_id` | string (uuid) \| null | | The identifier SparkLayer uses for the purchase. Length: min 1. |
| `[].platform_id` | string | | The identifier for this transaction on the e-commerce platform. Length: min 1. |
| `[].full_transaction` | string | | A JSON string representing the full details of the transaction |
| `[].type` | string | | The type of the transaction e.g. charge, refund |
| `[].apply_to_balance` | boolean | | Set to true to signal that the value of this transaction should contribute to customer balances |
| `[].currency_code` | string | | The 3 letter currency code used in this transaction. Length: min 3, max 3. |
| `[].total` | string | | The amount of this transaction |
| `[].transaction_date` | string (date-time) | | The date the transaction was created |
| `[].created_at` | string (date-time) | | The date the transaction was created in SparkLayer (RFC-3339). This is read only - it should not be sent to the API, but will be returned from it |

```json
[
  {
    "id": "63428136-658f-48a6-beb7-7f333dfd9686",
    "purchase_spark_id": "63428136-658f-48a6-beb7-7f333dfd9686",
    "platform_id": "123456789",
    "full_transaction": "<full_transaction>",
    "type": "<type>",
    "apply_to_balance": true,
    "currency_code": "GBP",
    "total": "20.99",
    "transaction_date": "2020-01-01T00:00:00+02:00",
    "created_at": "2020-01-01T00:00:00+02:00"
  }
]
```

#### 404: Not found.

`application/problem+json`: the standard error body (below).

#### 500: An unexpected error.

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |
| `errors` | object[] | | |
| `errors[].code` | string | | A machine-readable error message |
| `errors[].property` | string | | The offending property |
| `errors[].message` | string | | A human-readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://hub.sparklayer.io/tech-docs",
  "errors": [
    {
      "code": "unique-constraint-violation",
      "property": "purchase_identifiers.sparklayer",
      "message": "Each stock level must have a unique stock location and sku combination"
    }
  ]
}
```


---

# Create or update a purchase transaction

URL: https://docs.sparklayer.io/developers/api/purchasing/create-or-update-a-purchase-transaction
Operation: `PUT /api/v1/purchases/{lookupBy}/{identifier}/transactions` (operationId `createTransaction`)
OpenAPI spec: https://docs.sparklayer.io/openapi/purchasing.yaml

Records a transaction, such as a payment or refund, against the purchase that matches `lookupBy` and `identifier`. A transaction is identified by its purchase and `platform_id` (the transaction's ID in the third-party system), so sending a `platform_id` again updates that transaction. `total` is positive for a payment and negative for a refund.

With `apply_to_balance: true`, the transaction counts towards the purchase's payment status, adds an entry to the purchase history shown to the customer, and adjusts the customer's outstanding balance. With `false`, it's stored for information only, which is useful for pending or failed transactions. Changing it from `true` to `false` reverses those effects. `full_transaction` is stored exactly as sent, so remove sensitive data such as card numbers first. Don't also send the same transaction to your eCommerce platform, or it may be recorded twice.

`PUT /api/v1/purchases/{lookupBy}/{identifier}/transactions`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PUT "https://app.sparklayer.io/api/v1/purchases/platform/123456789/transactions" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "platform_id": "123456789",
  "full_transaction": "<full_transaction>",
  "type": "<type>",
  "apply_to_balance": true,
  "currency_code": "GBP",
  "total": "20.99",
  "transaction_date": "2020-01-01T00:00:00+02:00"
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `lookupBy` | "sparklayer" \| "platform" \| "internal" \| "visible" | Yes | Which of the purchase's `purchase_identifiers` `identifier` is: `sparklayer`, `platform`, `internal` or `visible`. Example: `platform` |
| `identifier` | string \| string (uuid) | Yes | The purchase identifier, of the kind set by `lookupBy`. With `lookupBy=sparklayer` it must be a UUID. Example: `123456789` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Length: min 1. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `platform_id` | string | Yes | The identifier for this transaction on the e-commerce platform. Length: min 1. |
| `full_transaction` | string | Yes | A JSON string representing the full details of the transaction |
| `type` | string | Yes | The type of the transaction e.g. charge, refund |
| `apply_to_balance` | boolean | Yes | Set to true to signal that the value of this transaction should contribute to customer balances |
| `currency_code` | string | Yes | The 3 letter currency code used in this transaction. Length: min 3, max 3. |
| `total` | string | Yes | The amount of this transaction |
| `transaction_date` | string (date-time) | Yes | The date the transaction was created |

```json
{
  "platform_id": "123456789",
  "full_transaction": "<full_transaction>",
  "type": "<type>",
  "apply_to_balance": true,
  "currency_code": "GBP",
  "total": "20.99",
  "transaction_date": "2020-01-01T00:00:00+02:00"
}
```

### Responses

#### 200: The created or updated transaction.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) \| null | | The identifier SparkLayer uses for the transaction. Length: min 1. |
| `purchase_spark_id` | string (uuid) \| null | | The identifier SparkLayer uses for the purchase. Length: min 1. |
| `platform_id` | string | | The identifier for this transaction on the e-commerce platform. Length: min 1. |
| `full_transaction` | string | | A JSON string representing the full details of the transaction |
| `type` | string | | The type of the transaction e.g. charge, refund |
| `apply_to_balance` | boolean | | Set to true to signal that the value of this transaction should contribute to customer balances |
| `currency_code` | string | | The 3 letter currency code used in this transaction. Length: min 3, max 3. |
| `total` | string | | The amount of this transaction |
| `transaction_date` | string (date-time) | | The date the transaction was created |
| `created_at` | string (date-time) | | The date the transaction was created in SparkLayer (RFC-3339). This is read only - it should not be sent to the API, but will be returned from it |

```json
{
  "id": "63428136-658f-48a6-beb7-7f333dfd9686",
  "purchase_spark_id": "63428136-658f-48a6-beb7-7f333dfd9686",
  "platform_id": "123456789",
  "full_transaction": "<full_transaction>",
  "type": "<type>",
  "apply_to_balance": true,
  "currency_code": "GBP",
  "total": "20.99",
  "transaction_date": "2020-01-01T00:00:00+02:00",
  "created_at": "2020-01-01T00:00:00+02:00"
}
```

#### 404: Not found.

`application/problem+json`: the standard error body (below).

#### 500: An unexpected error.

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |
| `errors` | object[] | | |
| `errors[].code` | string | | A machine-readable error message |
| `errors[].property` | string | | The offending property |
| `errors[].message` | string | | A human-readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://hub.sparklayer.io/tech-docs",
  "errors": [
    {
      "code": "unique-constraint-violation",
      "property": "purchase_identifiers.sparklayer",
      "message": "Each stock level must have a unique stock location and sku combination"
    }
  ]
}
```


---

# Get the store currency

URL: https://docs.sparklayer.io/developers/api/purchasing/get-store-currency
Operation: `GET /api/v1/store-currency` (operationId `getStoreCurrency`)
OpenAPI spec: https://docs.sparklayer.io/openapi/purchasing.yaml

Returns the store's base currency as an ISO 4217 `currency_code`, such as `GBP`. Returns `404` if no base currency has been set.

`GET /api/v1/store-currency`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/store-currency" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Length: min 1. Example: `jones-climbing` |

### Responses

#### 200: The store base currency

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `currency_code` | string | Yes | Length: min 3, max 3. |

```json
{
  "currency_code": "GBP"
}
```

#### 404: Store base currency not set


---

# Update the store currency

URL: https://docs.sparklayer.io/developers/api/purchasing/update-store-currency
Operation: `PUT /api/v1/store-currency` (operationId `putStoreCurrency`)
OpenAPI spec: https://docs.sparklayer.io/openapi/purchasing.yaml

Sets the store's base currency to the ISO 4217 `currency_code` you send, such as `GBP`, and returns it. Returns `409` if the base currency is already set to a different value.

`PUT /api/v1/store-currency`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PUT "https://app.sparklayer.io/api/v1/store-currency" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "currency_code": "GBP"
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Length: min 1. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `currency_code` | string | Yes | An ISO 4217 currency code. Length: min 3, max 3. |

```json
{
  "currency_code": "GBP"
}
```

### Responses

#### 200: Store base currency set successfully

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `currency_code` | string | Yes | Length: min 3, max 3. |

```json
{
  "currency_code": "GBP"
}
```

#### 409: Store base currency already set to a different value


---

# Get a customer's SKU order stats

URL: https://docs.sparklayer.io/developers/api/purchasing/get-order-stats-for-a-customer
Operation: `GET /api/v1/purchases/stats/order/sku` (operationId `getSKUSalesStats`)
OpenAPI spec: https://docs.sparklayer.io/openapi/purchasing.yaml

Returns how many units of each SKU a customer ordered between `start_date` and `end_date`, grouped by `week`, `month` or `quarter`. Give both dates as RFC 3339 date-times with a time zone offset, or `Z` for UTC. Each period is identified by its start date, returned in UTC.

`GET /api/v1/purchases/stats/order/sku`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/purchases/stats/order/sku?start_date=2020-01-01T00%3A00%3A00%2B02%3A00&end_date=2020-04-30T23%3A59%3A59%2B02%3A00&date_period_type=week" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `spark_customer_id` | string | Yes | The customer's SparkLayer ID. Length: min 1. |
| `start_date` | string (date-time) | Yes | Starting date-time from which to get stats - include user timezone or Z for UTC (RFC-3339). Example: `2020-01-01T00:00:00+02:00` |
| `end_date` | string (date-time) | Yes | Ending date-time until which to get stats - include user timezone or Z for UTC (RFC-3339). Example: `2020-04-30T23:59:59+02:00` |
| `date_period_type` | "week" \| "month" \| "quarter" | Yes | Date period type to group stats by |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Length: min 1. Example: `jones-climbing` |

### Responses

#### 200: The units ordered of each SKU, per period.

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].sku` | string | | |
| `[].periods` | object[] | | |
| `[].periods[].period_start_date` | string (date-time) | | Start date of the period group - always returned as UTC (RFC-3339) |
| `[].periods[].sold_qty` | integer | | |

```json
[
  {
    "sku": "SKU999",
    "periods": [
      {
        "period_start_date": "2020-01-01T00:00:00Z",
        "sold_qty": 8
      },
      {
        "period_start_date": "2020-02-01T00:00:00Z",
        "sold_qty": 2
      }
    ]
  },
  {
    "sku": "SKU888",
    "periods": [
      {
        "period_start_date": "2020-01-01T00:00:00Z",
        "sold_qty": 1
      },
      {
        "period_start_date": "2020-03-01T00:00:00Z",
        "sold_qty": 8
      }
    ]
  }
]
```


---

# Stock API

URL: https://docs.sparklayer.io/developers/api/stock

The Stock API reads, batch updates and deletes stock levels by SKU and manages stock locations for your SparkLayer site. Lists every endpoint and its responses.

The Stock API holds the stock level of each SKU at each of your stock locations, such as warehouses. SparkLayer uses these levels to show stock on the storefront.

## How it works

- **Stock locations** identify where stock is held. Each has a SparkLayer `id` and your own `external_id`, and you can use either to refer to it.
- **Stock levels** are set in bulk: **Update stock levels for multiple SKUs** creates or overwrites the level for each SKU and location pair you send, and leaves other pairs unchanged.
- **Get stock levels for multiple SKUs** only returns the location with the external ID `default` unless you ask for all locations or specific ones.

## Endpoints

- [POST Get stock levels for multiple SKUs](https://docs.sparklayer.io/developers/api/stock/get-stock-levels.md)
- [POST Update stock levels for multiple SKUs](https://docs.sparklayer.io/developers/api/stock/update-stock-levels.md)
- [POST Delete stock levels for multiple SKUs](https://docs.sparklayer.io/developers/api/stock/delete-stock-levels.md)
- [GET List stock locations](https://docs.sparklayer.io/developers/api/stock/list-stock-locations.md)
- [POST Create a stock location](https://docs.sparklayer.io/developers/api/stock/create-a-stock-location.md)
- [GET Get a stock location](https://docs.sparklayer.io/developers/api/stock/get-a-stock-location.md)
- [PATCH Update a stock location](https://docs.sparklayer.io/developers/api/stock/update-a-stock-location.md)
- [DELETE Delete a stock location](https://docs.sparklayer.io/developers/api/stock/delete-a-stock-location.md)

## Next steps

- [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md): how stock levels show to B2B customers.
- [Pricing API](https://docs.sparklayer.io/developers/api/pricing.md): sync prices alongside stock.


---

# Get stock levels for multiple SKUs

URL: https://docs.sparklayer.io/developers/api/stock/get-stock-levels
Operation: `POST /api/v1/batch-fetch-stock` (operationId `getBatchStock`)
OpenAPI spec: https://docs.sparklayer.io/openapi/stock.yaml

Returns stock levels for the SKUs in `skus`, grouped by SKU. By default only the stock location with the external ID `default` is included: set `filter.all_stock_locations` to `true` to include every location, or pass `filter.stock_location_ids` to choose specific ones. SKUs with no matching stock levels are left out of the response.

`POST /api/v1/batch-fetch-stock`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/batch-fetch-stock" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "skus": [
    "SKU-1"
  ],
  "filter": {
    "stock_location_ids": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "all_stock_locations": true
  }
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `skus` | string[] | | The SKUs to get stock levels for. |
| `filter` | object | | Which stock locations to include. Without it, only the location with the external ID `default` is included. |
| `filter.stock_location_ids` | (string (uuid))[] | | |
| `filter.all_stock_locations` | boolean | | |

```json
{
  "skus": [
    "SKU-1"
  ],
  "filter": {
    "stock_location_ids": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "all_stock_locations": true
  }
}
```

### Responses

#### 200: The stock levels of each requested SKU that has any, grouped by SKU.

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].sku` | string | | Product Variant SKU |
| `[].stock_levels` | object[] | | Stock levels for the SKU at each location |
| `[].stock_levels[].stock_level` | integer (int32) | | Quantity of stock held at the location. Default: `0`. |
| `[].stock_levels[].restock_date` | string (date) \| null | | Restock Date |
| `[].stock_levels[].min_stock_level` | integer (int32) | | Allow pre-ordering / overselling up to this qty. For example, if set to -9 and stock level was 0, 9 units could be sold. Default: `0`. |
| `[].stock_levels[].created_at` | string (date-time) | | |
| `[].stock_levels[].updated_at` | string (date-time) | | |
| `[].stock_levels[].stock_location_id` | string (uuid) | | Stock Location ID (internal UUID) |
| `[].stock_levels[].stock_location_name` | string | | Stock Location Name |

```json
[
  {
    "sku": "SKU-1",
    "stock_levels": [
      {
        "stock_level": 9,
        "restock_date": "2020-01-01",
        "min_stock_level": -9,
        "created_at": "2026-01-31T09:00:00Z",
        "updated_at": "2026-01-31T09:00:00Z",
        "stock_location_id": "123e4567-e89b-12d3-a456-426614174000",
        "stock_location_name": "Main Warehouse"
      }
    ]
  }
]
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Update stock levels for multiple SKUs

URL: https://docs.sparklayer.io/developers/api/stock/update-stock-levels
Operation: `POST /api/v1/batch-update-stock` (operationId `updateBatchStock`)
OpenAPI spec: https://docs.sparklayer.io/openapi/stock.yaml

Creates or updates the stock level for each SKU and stock location pair in the array. Identify the location with either `stock_location_id` or `stock_location_external_id`, not both. The stored values for each pair you send are overwritten; pairs you leave out are unchanged.

Returns `400` if a `stock_location_external_id` does not exist, or if the same SKU and location appear more than once in the request.

`POST /api/v1/batch-update-stock`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/batch-update-stock" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "stock_location_id": "123e4567-e89b-12d3-a456-426614174000",
    "sku": "SKU-1",
    "stock_level": 9,
    "restock_date": "2020-01-01",
    "min_stock_level": -9
  }
]'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

An array. Each item is one of these:

**BatchUpdateStockLevelByLocationId**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].stock_location_id` | string (uuid) | Yes | Stock Location ID (internal UUID) |
| `[].sku` | string | Yes | Product Variant SKU. Length: max 128. |
| `[].stock_level` | integer (int32) | Yes | Quantity of stock held at the location. Default: `0`. |
| `[].restock_date` | string (date) \| null | | Restock Date |
| `[].min_stock_level` | integer (int32) | | Allow pre-ordering / overselling up to this qty. For example, if set to -9 and stock level was 0, 9 units could be sold. Default: `0`. |

**BatchUpdateStockLevelByExternalLocationId**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].stock_location_external_id` | string | Yes | External ID (must be unique for the site). Length: max 255. |
| `[].sku` | string | Yes | Product Variant SKU. Length: max 128. |
| `[].stock_level` | integer (int32) | Yes | Quantity of stock held at the location. Default: `0`. |
| `[].restock_date` | string (date) \| null | | Restock Date |
| `[].min_stock_level` | integer (int32) | | Allow pre-ordering / overselling up to this qty. For example, if set to -9 and stock level was 0, 9 units could be sold. Default: `0`. |

```json
[
  {
    "stock_location_id": "123e4567-e89b-12d3-a456-426614174000",
    "sku": "SKU-1",
    "stock_level": 9,
    "restock_date": "2020-01-01",
    "min_stock_level": -9
  }
]
```

### Responses

#### 204: The stock levels were saved. No body.

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Delete stock levels for multiple SKUs

URL: https://docs.sparklayer.io/developers/api/stock/delete-stock-levels
Operation: `POST /api/v1/batch-delete-stock` (operationId `deleteBatchStock`)
OpenAPI spec: https://docs.sparklayer.io/openapi/stock.yaml

Deletes the stock levels at every stock location for the SKUs in `skus`. SKUs that have no stock levels are ignored.

`POST /api/v1/batch-delete-stock`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/batch-delete-stock" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "skus": [
    "SKU-1"
  ]
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `skus` | string[] | | The SKUs whose stock levels to delete, at every stock location. |

```json
{
  "skus": [
    "SKU-1"
  ]
}
```

### Responses

#### 204: The stock levels were deleted. No body.

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# List stock locations

URL: https://docs.sparklayer.io/developers/api/stock/list-stock-locations
Operation: `GET /api/v1/stock-locations` (operationId `getStockLocations`)
OpenAPI spec: https://docs.sparklayer.io/openapi/stock.yaml

Returns all stock locations for the site. The list is not paginated.

`GET /api/v1/stock-locations`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/stock-locations" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: Successful response (ordered by ID - asc)

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].id` | string (uuid) | | SparkLayer site Stock Location ID |
| `[].name` | string | Yes | Name. Length: max 255. |
| `[].external_id` | string | Yes | External ID (must be unique for the site). Length: max 255. |
| `[].created_at` | string (date-time) | | |
| `[].updated_at` | string (date-time) | | |

```json
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Stock Warehouse 1",
    "external_id": "warehouse-1",
    "created_at": "2026-01-31T09:00:00Z",
    "updated_at": "2026-01-31T09:00:00Z"
  }
]
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Create a stock location

URL: https://docs.sparklayer.io/developers/api/stock/create-a-stock-location
Operation: `POST /api/v1/stock-locations` (operationId `createStockLocation`)
OpenAPI spec: https://docs.sparklayer.io/openapi/stock.yaml

`name` and `external_id` are required, and `external_id` must be unique for the site: a duplicate returns `409`. Returns the new location, including its SparkLayer `id`.

`POST /api/v1/stock-locations`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/stock-locations" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Stock Warehouse 1",
  "external_id": "warehouse-1"
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Name. Length: max 255. |
| `external_id` | string | Yes | External ID (must be unique for the site). Length: max 255. |

```json
{
  "name": "Stock Warehouse 1",
  "external_id": "warehouse-1"
}
```

### Responses

#### 200: The new stock location, including its SparkLayer `id`.

The `StockLocation` object: the request body's fields, plus:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | | SparkLayer site Stock Location ID |
| `created_at` | string (date-time) | | |
| `updated_at` | string (date-time) | | |

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Stock Warehouse 1",
  "external_id": "warehouse-1",
  "created_at": "2026-01-31T09:00:00Z",
  "updated_at": "2026-01-31T09:00:00Z"
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Get a stock location

URL: https://docs.sparklayer.io/developers/api/stock/get-a-stock-location
Operation: `GET /api/v1/stock-locations/{StockLocationID}` (operationId `getStockLocation`)
OpenAPI spec: https://docs.sparklayer.io/openapi/stock.yaml

Looks up a stock location by its SparkLayer ID or its `external_id`. Returns `404` if no location matches.

`GET /api/v1/stock-locations/{StockLocationID}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/stock-locations/warehouse-1" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `StockLocationID` | string | Yes | The stock location's SparkLayer ID or its `external_id`. Example: `warehouse-1` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: The stock location.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | | SparkLayer site Stock Location ID |
| `name` | string | Yes | Name. Length: max 255. |
| `external_id` | string | Yes | External ID (must be unique for the site). Length: max 255. |
| `created_at` | string (date-time) | | |
| `updated_at` | string (date-time) | | |

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Stock Warehouse 1",
  "external_id": "warehouse-1",
  "created_at": "2026-01-31T09:00:00Z",
  "updated_at": "2026-01-31T09:00:00Z"
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Delete a stock location

URL: https://docs.sparklayer.io/developers/api/stock/delete-a-stock-location
Operation: `DELETE /api/v1/stock-locations/{StockLocationID}` (operationId `deleteStockLocation`)
OpenAPI spec: https://docs.sparklayer.io/openapi/stock.yaml

Deletes the stock location, identified by its SparkLayer ID or `external_id`, together with all stock levels held at it. Returns `204` even if no location matched.

`DELETE /api/v1/stock-locations/{StockLocationID}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X DELETE "https://app.sparklayer.io/api/v1/stock-locations/warehouse-1" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `StockLocationID` | string | Yes | The stock location's SparkLayer ID or its `external_id`. Example: `warehouse-1` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 204: No body. Returned even if no location matched.

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Update a stock location

URL: https://docs.sparklayer.io/developers/api/stock/update-a-stock-location
Operation: `PATCH /api/v1/stock-locations/{StockLocationID}` (operationId `updateStockLocation`)
OpenAPI spec: https://docs.sparklayer.io/openapi/stock.yaml

Replaces the location's `name` and `external_id`, which are both required. Identify the location by its SparkLayer ID or its current `external_id`. Returns `404` if no location matches, and `409` if the new `external_id` is already used by another location.

`PATCH /api/v1/stock-locations/{StockLocationID}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PATCH "https://app.sparklayer.io/api/v1/stock-locations/warehouse-1" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Stock Warehouse 1",
  "external_id": "warehouse-1"
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `StockLocationID` | string | Yes | The stock location's SparkLayer ID or its `external_id`. Example: `warehouse-1` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Name. Length: max 255. |
| `external_id` | string | Yes | External ID (must be unique for the site). Length: max 255. |

```json
{
  "name": "Stock Warehouse 1",
  "external_id": "warehouse-1"
}
```

### Responses

#### 200: The updated stock location.

The `StockLocation` object: the request body's fields, plus:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | | SparkLayer site Stock Location ID |
| `created_at` | string (date-time) | | |
| `updated_at` | string (date-time) | | |

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Stock Warehouse 1",
  "external_id": "warehouse-1",
  "created_at": "2026-01-31T09:00:00Z",
  "updated_at": "2026-01-31T09:00:00Z"
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Files API

URL: https://docs.sparklayer.io/developers/api/files

Upload, update and download files with the SparkLayer Files API using expiring URLs, and retrieve order file attachments from their GIDs. Lists all endpoints.

The Files API stores and retrieves files in SparkLayer. SparkLayer uses it for order file attachments, and you can use it to upload files or download the files attached to your orders.

## How it works

> **URLs expire**
>
> The upload and download URLs returned by the API expire after 15 minutes.

### Uploading a file

Uploading takes two requests:

1. [Create a file](https://docs.sparklayer.io/developers/api/files/create-a-new-file.md) (`POST /api/v1/files`) with the file's path, including its name, in `file_path`. Like every API request, it needs your access token and Site ID:

   ```bash title="Create a file"
   curl -X POST https://app.sparklayer.io/api/v1/files \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Site-Id: <SITE_ID>" \
     -H "Content-Type: application/json" \
     -d '{ "file_path": "folder/file.pdf" }'
   ```

   The response includes the file's `id`, a signed upload `url` and a list of `required_headers`.

2. Upload the file's contents with an HTTP `PUT` to that `url`, sending **every** header in `required_headers` (for example `Content-Type`). If any are missing, the upload fails. The signed URL grants access by itself, so this request doesn't need your `Authorization` or `Site-Id` headers:

   ```bash title="Upload the contents"
   curl --upload-file 'file.pdf' \
     -H "Content-Type: application/pdf" \
     '<UPLOAD_URL>'
   ```

Files can be up to 20 MB. Use the file's `id` with the other endpoints. To replace a file's contents, [update the file](https://docs.sparklayer.io/developers/api/files/update-a-file.md) (`PATCH /api/v1/files/{id}`) to get a new upload URL, then upload again. 

### Downloading a file

To download a file, [get the file](https://docs.sparklayer.io/developers/api/files/get-a-file.md) (`GET /api/v1/files/{id}`). Once the upload has completed, this returns a download URL, some file metadata and a list of `required_headers`. Download the file from the URL, sending those headers.

### Failed uploads

If the file's contents don't match its file extension, the file is deleted, and `GET /api/v1/files/{id}` returns `410 Gone`.

### Downloading order file attachments

To download the files attached to a B2B order, use `GET /api/v1/files/{id}`. SparkLayer stores the IDs of attached files in the order's note attributes, under the name set in `checkoutCustomElements` in your theme (`file-upload` by default). They're stored as a JSON array:

```json title="Order note attribute"
[
  "gid://sparklayer/File/fdc70d92-fcdf-4719-af2b-9d319a5035d2",
  "gid://sparklayer/File/a7a3ee08-c6d0-49ee-89b4-bcdaf780d553",
  "gid://sparklayer/File/15be5381-0b50-459f-9643-af236b9f29f7"
]
```

Remove the `gid://sparklayer/File/` prefix from each one to get the file ID, for example `fdc70d92-fcdf-4719-af2b-9d319a5035d2`.

## Endpoints

- [GET Get multiple files](https://docs.sparklayer.io/developers/api/files/get-bulk-files.md)
- [POST Create a file](https://docs.sparklayer.io/developers/api/files/create-a-new-file.md)
- [DELETE Delete all files](https://docs.sparklayer.io/developers/api/files/delete-all-files.md)
- [POST Search files by metadata](https://docs.sparklayer.io/developers/api/files/query-files-by-metadata.md)
- [GET Get a file](https://docs.sparklayer.io/developers/api/files/get-a-file.md)
- [PATCH Update a file](https://docs.sparklayer.io/developers/api/files/update-a-file.md)
- [DELETE Delete a file](https://docs.sparklayer.io/developers/api/files/delete-a-file.md)
- [POST Delete multiple files](https://docs.sparklayer.io/developers/api/files/delete-multiple-files.md)

## Next steps

- [Authentication](https://docs.sparklayer.io/developers/authentication.md): get the access token the API requests need.
- [Custom attributes and files](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#custom-attributes-and-files): let customers attach files to cart items.
- [Purchasing API](https://docs.sparklayer.io/developers/api/purchasing.md): look up the orders the files belong to.


---

# Get multiple files

URL: https://docs.sparklayer.io/developers/api/files/get-bulk-files
Operation: `GET /api/v1/files` (operationId `getBulkFiles`)
OpenAPI spec: https://docs.sparklayer.io/openapi/files.yaml

Returns the files whose IDs you pass in `ids`; repeat the parameter for each ID (`?ids=…&ids=…`). IDs that do not exist, or whose files have been deleted or have expired, are left out of the response. If any requested file failed its post-upload checks, the whole request returns `410`.

`GET /api/v1/files`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/files?ids=86027e2c-e853-11ee-b1d4-7c214a6ed8c7" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `ids` | string[] | Yes | The IDs of the files to get. Repeat the parameter for each ID (`?ids=…&ids=…`). Example: `86027e2c-e853-11ee-b1d4-7c214a6ed8c7` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: The requested files that exist. IDs that don't, or whose files were deleted or expired, are left out.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `file_handle` | object | | |
| `file_handle.file_path` | string | | The path to the file, including the file name |
| `file_handle.id` | string | | The ID of this type |
| `file_handle.url` | string \| null | | URL to download/upload the file. For GET, this will be a readable link. If the file is not ready, this will be `null`. For POST/PATCH this will be a writeable link |
| `file_handle.required_headers` | object[] | | An array of headers you must include in the file upload/download request |
| `file_handle.required_headers[].name` | string | | Name of the header |
| `file_handle.required_headers[].value` | string | | Value of the header |
| `ready` | boolean | | Whether the file has been fully uploaded and verified |
| `mime_type` | string | | The mime type of this file |
| `file_size` | integer | | The size of this file in bytes |
| `created_at` | string (date-time) | | The date at which the file was created (RFC-3339) |
| `updated_at` | string (date-time) | | The date at which the file was updated (RFC-3339) |
| `metadata` | object | | |

```json
{
  "file_handle": {
    "file_path": "folder/file.png",
    "id": "86027e2c-e853-11ee-b1d4-7c214a6ed8c7",
    "url": "https://files.sparklayer.io/siteId/siteEnv/path/to/file.png.",
    "required_headers": [
      {
        "name": "Content-Type",
        "value": "application/pdf"
      }
    ]
  },
  "ready": true,
  "mime_type": "image/png",
  "file_size": 255,
  "created_at": "2020-01-01T00:00:00+02:00",
  "updated_at": "2020-01-01T00:00:00+02:00",
  "metadata": {
    "sparklayer": {
      "forms": {
        "context": "email_template",
        "step_id": "erkjs"
      },
      "emails": {
        "attachments": [
          "86027e2c-e853-11ee-b1d4-7c214a6ed8c7"
        ]
      }
    }
  }
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "template",
      "message": "template not found"
    }
  ]
}
```


---

# Create a file

URL: https://docs.sparklayer.io/developers/api/files/create-a-new-file
Operation: `POST /api/v1/files` (operationId `createFile`)
OpenAPI spec: https://docs.sparklayer.io/openapi/files.yaml

Registers a file and returns a signed upload URL. Upload the contents with an HTTP `PUT` to `url`, sending the `required_headers`, within 15 minutes; files can be up to 20 MB. The file type comes from the extension in `file_path` and must be on the allowed list (including PDF, CSV, common image formats and Office documents).

Once uploaded, the contents are checked against the extension and the file becomes `ready` when the checks pass. Set `expires_at` to have the file deleted automatically.

`POST /api/v1/files`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/files" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "file_path": "folder/file.png",
  "expires_at": "2017-07-21T17:32:28Z",
  "metadata": {
    "sparklayer": {
      "forms": {
        "context": "email_template",
        "step_id": "erkjs"
      },
      "emails": {
        "attachments": [
          "86027e2c-e853-11ee-b1d4-7c214a6ed8c7"
        ]
      }
    }
  }
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `file_path` | string | Yes | The path to the file, including the file name |
| `expires_at` | string (date-time) | | An optional RFC3339 date string indicating when a file should be auto deleted |
| `metadata` | object | | Metadata attached to the file |

```json
{
  "file_path": "folder/file.png",
  "expires_at": "2017-07-21T17:32:28Z",
  "metadata": {
    "sparklayer": {
      "forms": {
        "context": "email_template",
        "step_id": "erkjs"
      },
      "emails": {
        "attachments": [
          "86027e2c-e853-11ee-b1d4-7c214a6ed8c7"
        ]
      }
    }
  }
}
```

### Responses

#### 202: The file was registered. Upload its contents with an HTTP `PUT` to `url`, sending the `required_headers`, within 15 minutes.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `file_path` | string | | The path to the file, including the file name |
| `id` | string | | The ID of this type |
| `url` | string \| null | | URL to download/upload the file. For GET, this will be a readable link. If the file is not ready, this will be `null`. For POST/PATCH this will be a writeable link |
| `required_headers` | object[] | | An array of headers you must include in the file upload/download request |
| `required_headers[].name` | string | | Name of the header |
| `required_headers[].value` | string | | Value of the header |

```json
{
  "file_path": "folder/file.png",
  "id": "86027e2c-e853-11ee-b1d4-7c214a6ed8c7",
  "url": "https://files.sparklayer.io/siteId/siteEnv/path/to/file.png.",
  "required_headers": [
    {
      "name": "Content-Type",
      "value": "application/pdf"
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "template",
      "message": "template not found"
    }
  ]
}
```


---

# Delete all files

URL: https://docs.sparklayer.io/developers/api/files/delete-all-files
Operation: `DELETE /api/v1/files` (operationId `deleteAllClientFiles`)
OpenAPI spec: https://docs.sparklayer.io/openapi/files.yaml

Permanently deletes every file for the site in the current environment (live or test), including the stored contents.

`DELETE /api/v1/files`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X DELETE "https://app.sparklayer.io/api/v1/files" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 204: Every file was deleted. No body.

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "template",
      "message": "template not found"
    }
  ]
}
```


---

# Search files by metadata

URL: https://docs.sparklayer.io/developers/api/files/query-files-by-metadata
Operation: `POST /api/v1/search-files` (operationId `fileSearch`)
OpenAPI spec: https://docs.sparklayer.io/openapi/files.yaml

Returns every file whose `metadata` contains the JSON object you send (PostgreSQL JSON containment). Files that failed their post-upload checks are included and flagged with `rejected: true`. Deleted and expired files are excluded, and results are not paginated.

`POST /api/v1/search-files`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/search-files" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "sparklayer": {
      "forms": {
        "context": "email_template"
      }
    }
  }
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `metadata` | any \| null | Yes | Returns all files who's metadata contains this JSON. See: https://www.postgresql.org/docs/current/datatype-json.html#JSON-CONTAINMENT |

```json
{
  "metadata": {
    "sparklayer": {
      "forms": {
        "context": "email_template"
      }
    }
  }
}
```

### Responses

#### 200: The matching files.

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].file_handle` | object | | |
| `[].file_handle.file_path` | string | | The path to the file, including the file name |
| `[].file_handle.id` | string | | The ID of this type |
| `[].file_handle.url` | string \| null | | URL to download/upload the file. For GET, this will be a readable link. If the file is not ready, this will be `null`. For POST/PATCH this will be a writeable link |
| `[].file_handle.required_headers` | object[] | | An array of headers you must include in the file upload/download request |
| `[].file_handle.required_headers[].name` | string | | Name of the header |
| `[].file_handle.required_headers[].value` | string | | Value of the header |
| `[].ready` | boolean | | Whether the file has been fully uploaded and verified |
| `[].mime_type` | string | | The mime type of this file |
| `[].file_size` | integer | | The size of this file in bytes |
| `[].created_at` | string (date-time) | | The date at which the file was created (RFC-3339) |
| `[].updated_at` | string (date-time) | | The date at which the file was updated (RFC-3339) |
| `[].metadata` | object | | |
| `[].rejected` | boolean | | |

```json
[
  {
    "file_handle": {
      "file_path": "folder/file.png",
      "id": "86027e2c-e853-11ee-b1d4-7c214a6ed8c7",
      "url": "https://files.sparklayer.io/siteId/siteEnv/path/to/file.png.",
      "required_headers": [
        {
          "name": "Content-Type",
          "value": "application/pdf"
        }
      ]
    },
    "ready": true,
    "mime_type": "image/png",
    "file_size": 255,
    "created_at": "2020-01-01T00:00:00+02:00",
    "updated_at": "2020-01-01T00:00:00+02:00",
    "metadata": {
      "sparklayer": {
        "forms": {
          "context": "email_template",
          "step_id": "erkjs"
        },
        "emails": {
          "attachments": [
            "86027e2c-e853-11ee-b1d4-7c214a6ed8c7"
          ]
        }
      }
    },
    "rejected": true
  }
]
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "template",
      "message": "template not found"
    }
  ]
}
```


---

# Get a file

URL: https://docs.sparklayer.io/developers/api/files/get-a-file
Operation: `GET /api/v1/files/{id}` (operationId `getFile`)
OpenAPI spec: https://docs.sparklayer.io/openapi/files.yaml

Returns the file. Once it is `ready`, the response includes a signed download URL that is valid for 15 minutes.

Returns `404` if the file does not exist, has been deleted or has expired, and `410` if it failed its post-upload checks (for example, its contents did not match its extension). Pass `allowRejected=true` to receive the file details with the `410`.

`GET /api/v1/files/{id}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/files/86027e2c-e853-11ee-b1d4-7c214a6ed8c7" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | Yes | The file's ID. Example: `86027e2c-e853-11ee-b1d4-7c214a6ed8c7` |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `allowRejected` | boolean | | Set to `true` to receive the file details with the `410` response when the file failed its post-upload checks. |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: The file, with a signed download `url` once it is `ready`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `file_handle` | object | | |
| `file_handle.file_path` | string | | The path to the file, including the file name |
| `file_handle.id` | string | | The ID of this type |
| `file_handle.url` | string \| null | | URL to download/upload the file. For GET, this will be a readable link. If the file is not ready, this will be `null`. For POST/PATCH this will be a writeable link |
| `file_handle.required_headers` | object[] | | An array of headers you must include in the file upload/download request |
| `file_handle.required_headers[].name` | string | | Name of the header |
| `file_handle.required_headers[].value` | string | | Value of the header |
| `ready` | boolean | | Whether the file has been fully uploaded and verified |
| `mime_type` | string | | The mime type of this file |
| `file_size` | integer | | The size of this file in bytes |
| `created_at` | string (date-time) | | The date at which the file was created (RFC-3339) |
| `updated_at` | string (date-time) | | The date at which the file was updated (RFC-3339) |
| `metadata` | object | | |

```json
{
  "file_handle": {
    "file_path": "folder/file.png",
    "id": "86027e2c-e853-11ee-b1d4-7c214a6ed8c7",
    "url": "https://files.sparklayer.io/siteId/siteEnv/path/to/file.png.",
    "required_headers": [
      {
        "name": "Content-Type",
        "value": "application/pdf"
      }
    ]
  },
  "ready": true,
  "mime_type": "image/png",
  "file_size": 255,
  "created_at": "2020-01-01T00:00:00+02:00",
  "updated_at": "2020-01-01T00:00:00+02:00",
  "metadata": {
    "sparklayer": {
      "forms": {
        "context": "email_template",
        "step_id": "erkjs"
      },
      "emails": {
        "attachments": [
          "86027e2c-e853-11ee-b1d4-7c214a6ed8c7"
        ]
      }
    }
  }
}
```

#### 410: The file failed its post-upload checks. The file details are included when `allowRejected=true`.

One of these:

- **Error**: the standard error body (below).

**File**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `file_handle` | object | | |
| `file_handle.file_path` | string | | The path to the file, including the file name |
| `file_handle.id` | string | | The ID of this type |
| `file_handle.url` | string \| null | | URL to download/upload the file. For GET, this will be a readable link. If the file is not ready, this will be `null`. For POST/PATCH this will be a writeable link |
| `file_handle.required_headers` | object[] | | An array of headers you must include in the file upload/download request |
| `file_handle.required_headers[].name` | string | | Name of the header |
| `file_handle.required_headers[].value` | string | | Value of the header |
| `ready` | boolean | | Whether the file has been fully uploaded and verified |
| `mime_type` | string | | The mime type of this file |
| `file_size` | integer | | The size of this file in bytes |
| `created_at` | string (date-time) | | The date at which the file was created (RFC-3339) |
| `updated_at` | string (date-time) | | The date at which the file was updated (RFC-3339) |
| `metadata` | object | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "template",
      "message": "template not found"
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "template",
      "message": "template not found"
    }
  ]
}
```


---

# Delete a file

URL: https://docs.sparklayer.io/developers/api/files/delete-a-file
Operation: `DELETE /api/v1/files/{id}` (operationId `deleteFile`)
OpenAPI spec: https://docs.sparklayer.io/openapi/files.yaml

Deletes the file and its stored contents. Returns `404` if the file does not exist or has already been deleted.

`DELETE /api/v1/files/{id}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X DELETE "https://app.sparklayer.io/api/v1/files/86027e2c-e853-11ee-b1d4-7c214a6ed8c7" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | Yes | The file's ID. Example: `86027e2c-e853-11ee-b1d4-7c214a6ed8c7` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 204: The file was deleted. No body.

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "template",
      "message": "template not found"
    }
  ]
}
```


---

# Update a file

URL: https://docs.sparklayer.io/developers/api/files/update-a-file
Operation: `PATCH /api/v1/files/{id}` (operationId `updateFile`)
OpenAPI spec: https://docs.sparklayer.io/openapi/files.yaml

Returns a new signed upload URL for an existing file so you can replace its contents: upload with an HTTP `PUT` to `url`, sending the `required_headers`, within 15 minutes. No request body is needed and the file path cannot be changed. Returns `404` if the file does not exist.

`PATCH /api/v1/files/{id}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PATCH "https://app.sparklayer.io/api/v1/files/86027e2c-e853-11ee-b1d4-7c214a6ed8c7" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | Yes | The file's ID. Example: `86027e2c-e853-11ee-b1d4-7c214a6ed8c7` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 202: A new signed upload `url` for the file. Upload with an HTTP `PUT`, sending the `required_headers`, within 15 minutes.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `file_path` | string | | The path to the file, including the file name |
| `id` | string | | The ID of this type |
| `url` | string \| null | | URL to download/upload the file. For GET, this will be a readable link. If the file is not ready, this will be `null`. For POST/PATCH this will be a writeable link |
| `required_headers` | object[] | | An array of headers you must include in the file upload/download request |
| `required_headers[].name` | string | | Name of the header |
| `required_headers[].value` | string | | Value of the header |

```json
{
  "file_path": "folder/file.png",
  "id": "86027e2c-e853-11ee-b1d4-7c214a6ed8c7",
  "url": "https://files.sparklayer.io/siteId/siteEnv/path/to/file.png.",
  "required_headers": [
    {
      "name": "Content-Type",
      "value": "application/pdf"
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "template",
      "message": "template not found"
    }
  ]
}
```


---

# Delete multiple files

URL: https://docs.sparklayer.io/developers/api/files/delete-multiple-files
Operation: `POST /api/v1/batch-delete-files` (operationId `deleteBulkFiles`)
OpenAPI spec: https://docs.sparklayer.io/openapi/files.yaml

Deletes the files whose IDs you send as a JSON array. IDs that do not exist are ignored. If some files could not be removed from storage, the response is a `500` whose `errors` give the affected file IDs in `property`, so you can retry just those.

`POST /api/v1/batch-delete-files`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/batch-delete-files" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '[
  "3f2b8c1e-5d4a-4e6f-9b7c-1a2d3e4f5a6b"
]'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

Type: `(string (uuid))[]`

```json
[
  "3f2b8c1e-5d4a-4e6f-9b7c-1a2d3e4f5a6b"
]
```

### Responses

#### 204: The files were deleted. No body.

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "template",
      "message": "template not found"
    }
  ]
}
```


---

# Sync Logging API

URL: https://docs.sparklayer.io/developers/api/sync-log

The Sync Logging API records full and partial data syncs, sync errors and status between your systems and SparkLayer. Lists every endpoint and its parameters.

The Sync Logging API records the progress of data syncs between an integration and SparkLayer — when full and partial syncs ran, and which records failed to sync and why. Logs are kept per integration and data type.

## How it works

1. **Record each full sync** with **Record a full sync** (`PUT`). This sets the `started_full_sync` and `last_full_sync` timestamps and replaces the logged errors with the ones you send. A timestamp you leave out is cleared.
   - For a quick sync, send one `PUT` when it finishes, with both timestamps and all the errors.
   - For a long or asynchronous sync, send a `PUT` with `started_full_sync` when it starts, record errors with `PATCH` requests as items sync, and send a final `PATCH` with `last_full_sync` once every item has synced.
2. **After each partial (incremental) sync**, use **Record a partial sync** (`PATCH`) to update `last_partial_sync`, clear errors for records that now sync successfully (listed in `successfully_synced`), and add new errors.
3. **Read the status and errors** with **Get a sync status** and **List sync errors**.

Record a full sync before any partial syncs: until one exists, the status endpoints return `404` and partial sync timestamps aren't saved. Each error's `external_id` must be unique within a request.

For how an Ignite integration logs its syncs, see [Ignite data sync](https://docs.sparklayer.io/ignite/data-sync.md#logging-sync-issues).

## Endpoints

- [DELETE Delete all sync logs](https://docs.sparklayer.io/developers/api/sync-log/delete-a-stores-sync-logs.md)
- [GET Get a sync status](https://docs.sparklayer.io/developers/api/sync-log/get-sync-logging-status.md)
- [PATCH Record a partial sync](https://docs.sparklayer.io/developers/api/sync-log/update-sync-logs-with-a-partial-sync.md)
- [PUT Record a full sync](https://docs.sparklayer.io/developers/api/sync-log/update-sync-logs-with-a-full-sync.md)
- [GET List sync errors](https://docs.sparklayer.io/developers/api/sync-log/get-sync-logging-status-errors.md)

## Next steps

- [Authentication](https://docs.sparklayer.io/developers/authentication.md): get an access token for your requests.
- [Ignite data sync](https://docs.sparklayer.io/ignite/data-sync.md): what to sync from a custom platform, and when.


---

# Delete all sync logs

URL: https://docs.sparklayer.io/developers/api/sync-log/delete-a-stores-sync-logs
Operation: `DELETE /api/v1/sync-log` (operationId `deleteAllLoggingStatus`)
OpenAPI spec: https://docs.sparklayer.io/openapi/sync-log.yaml

Deletes the sync status and logged errors for every integration and data type on the site, in the current environment (live or test).

`DELETE /api/v1/sync-log`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X DELETE "https://app.sparklayer.io/api/v1/sync-log" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 204: The sync logs were deleted. No body.

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://hub.sparklayer.io/tech-docs"
}
```


---

# Get a sync status

URL: https://docs.sparklayer.io/developers/api/sync-log/get-sync-logging-status
Operation: `GET /api/v1/sync-log/{integration}/{data_type}` (operationId `getLoggingStatus`)
OpenAPI spec: https://docs.sparklayer.io/openapi/sync-log.yaml

Returns the sync timestamps and the number of logged errors for the integration and data type. Returns `404` if no full sync has been recorded for them yet.

`GET /api/v1/sync-log/{integration}/{data_type}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/sync-log/shopify/products" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `integration` | string | Yes | The integration the sync log belongs to, such as `shopify`. Logs are kept separately for each integration and data type. Example: `shopify` |
| `data_type` | "products" \| "customers" \| "merchant" \| "purchases" \| "pricing" \| "accountancy" | Yes | The type of data the sync log is for. Example: `products` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: The sync timestamps and the number of logged errors.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `started_full_sync` | string (date-time) | | Started full sync |
| `last_full_sync` | string (date-time) | | Last full sync |
| `last_full_sync_succeeded` | boolean | | Was the last full sync successful? A successful sync may still have logging errors. A failed full sync may indicate integration configuration issues or timeout. |
| `last_partial_sync` | string (date-time) | | |
| `error_count` | integer | | Sync errors count |

```json
{
  "started_full_sync": "2023-01-01T01:01:01Z",
  "last_full_sync": "2023-01-01T01:01:01Z",
  "last_full_sync_succeeded": true,
  "last_partial_sync": "2023-01-01T01:01:01Z",
  "error_count": 3
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://hub.sparklayer.io/tech-docs"
}
```


---

# Record a full sync

URL: https://docs.sparklayer.io/developers/api/sync-log/update-sync-logs-with-a-full-sync
Operation: `PUT /api/v1/sync-log/{integration}/{data_type}` (operationId `updateFullLoggingStatus`)
OpenAPI spec: https://docs.sparklayer.io/openapi/sync-log.yaml

Sets `started_full_sync` and `last_full_sync` (a timestamp you omit is cleared) and replaces all previously logged errors for the integration and data type with the `errors` you send, up to 5,000. Each error's `external_id` must be unique within the request, otherwise you get a `400`.

`PUT /api/v1/sync-log/{integration}/{data_type}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PUT "https://app.sparklayer.io/api/v1/sync-log/shopify/products" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "started_full_sync": "2023-01-01T01:01:01Z",
  "last_full_sync": "2023-01-01T01:01:01Z",
  "last_full_sync_succeeded": true,
  "errors": [
    {
      "external_id": "ABC-123",
      "external_url": "https://example.com/products/ABC-123",
      "visible_name": "The ABC 123 Book",
      "api_response": "Error - Product ABC-123 not found",
      "friendly_error": "ABC-123 not found"
    }
  ]
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `integration` | string | Yes | The integration the sync log belongs to, such as `shopify`. Logs are kept separately for each integration and data type. Example: `shopify` |
| `data_type` | "products" \| "customers" \| "merchant" \| "purchases" \| "pricing" \| "accountancy" | Yes | The type of data the sync log is for. Example: `products` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `started_full_sync` | string (date-time) | Yes | Started full sync |
| `last_full_sync` | string (date-time) | | Last full sync |
| `last_full_sync_succeeded` | boolean | | Was the last full sync successful? A successful sync may still have logging errors. A failed full sync may indicate integration configuration issues or timeout. |
| `errors` | object[] | | The errors from this sync (up to 5,000). They replace every error logged before. Each `external_id` must be unique within the request. |
| `errors[].external_id` | string | | External ID. Length: min 1, max 64. |
| `errors[].external_url` | string | | External URL. Length: min 1, max 1024. |
| `errors[].visible_name` | string | | User friendly name. Length: max 1024. |
| `errors[].api_response` | string | | API response from sync. Length: min 1, max 4294967295. |
| `errors[].friendly_error` | string | | User friendly error. Length: min 1, max 4294967295. |

```json
{
  "started_full_sync": "2023-01-01T01:01:01Z",
  "last_full_sync": "2023-01-01T01:01:01Z",
  "last_full_sync_succeeded": true,
  "errors": [
    {
      "external_id": "ABC-123",
      "external_url": "https://example.com/products/ABC-123",
      "visible_name": "The ABC 123 Book",
      "api_response": "Error - Product ABC-123 not found",
      "friendly_error": "ABC-123 not found"
    }
  ]
}
```

### Responses

#### 204: The full sync was recorded. No body.

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://hub.sparklayer.io/tech-docs"
}
```


---

# Record a partial sync

URL: https://docs.sparklayer.io/developers/api/sync-log/update-sync-logs-with-a-partial-sync
Operation: `PATCH /api/v1/sync-log/{integration}/{data_type}` (operationId `updatePartialLoggingStatus`)
OpenAPI spec: https://docs.sparklayer.io/openapi/sync-log.yaml

Updates `last_partial_sync`, removes logged errors whose `external_id` is listed in `successfully_synced`, and adds or updates the `errors` you send, matched by `external_id`. Timestamps are only saved once a full sync has been recorded for the integration and data type. Each error's `external_id` must be unique within the request, otherwise you get a `400`.

`PATCH /api/v1/sync-log/{integration}/{data_type}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PATCH "https://app.sparklayer.io/api/v1/sync-log/shopify/products" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "last_partial_sync": "2023-01-01T01:01:01Z",
  "last_full_sync": "2023-01-01T01:01:01Z",
  "last_full_sync_succeeded": true,
  "errors": [
    {
      "external_id": "ABC-123",
      "external_url": "https://example.com/products/ABC-123",
      "visible_name": "The ABC 123 Book",
      "api_response": "Error - Product ABC-123 not found",
      "friendly_error": "ABC-123 not found"
    }
  ],
  "successfully_synced": [
    "ABC-123"
  ]
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `integration` | string | Yes | The integration the sync log belongs to, such as `shopify`. Logs are kept separately for each integration and data type. Example: `shopify` |
| `data_type` | "products" \| "customers" \| "merchant" \| "purchases" \| "pricing" \| "accountancy" | Yes | The type of data the sync log is for. Example: `products` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `last_partial_sync` | string (date-time) | Yes | When this partial sync ran. Only saved once a full sync has been recorded for the integration and data type. |
| `last_full_sync` | string (date-time) | | Last full sync |
| `last_full_sync_succeeded` | boolean | | Was the last full sync successful? A successful sync may still have logging errors. A failed full sync may indicate integration configuration issues or timeout. |
| `errors` | object[] | | Errors to add, or to update when an error with the same `external_id` is already logged. Each `external_id` must be unique within the request. |
| `errors[].external_id` | string | | External ID. Length: min 1, max 64. |
| `errors[].external_url` | string | | External URL. Length: min 1, max 1024. |
| `errors[].visible_name` | string | | User friendly name. Length: max 1024. |
| `errors[].api_response` | string | | API response from sync. Length: min 1, max 4294967295. |
| `errors[].friendly_error` | string | | User friendly error. Length: min 1, max 4294967295. |
| `successfully_synced` | string[] | | External IDs of records that now sync successfully: their logged errors are removed. |

```json
{
  "last_partial_sync": "2023-01-01T01:01:01Z",
  "last_full_sync": "2023-01-01T01:01:01Z",
  "last_full_sync_succeeded": true,
  "errors": [
    {
      "external_id": "ABC-123",
      "external_url": "https://example.com/products/ABC-123",
      "visible_name": "The ABC 123 Book",
      "api_response": "Error - Product ABC-123 not found",
      "friendly_error": "ABC-123 not found"
    }
  ],
  "successfully_synced": [
    "ABC-123"
  ]
}
```

### Responses

#### 204: The partial sync was recorded. No body.

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://hub.sparklayer.io/tech-docs"
}
```


---

# List sync errors

URL: https://docs.sparklayer.io/developers/api/sync-log/get-sync-logging-status-errors
Operation: `GET /api/v1/sync-log/{integration}/{data_type}/errors` (operationId `getLoggingStatusErrors`)
OpenAPI spec: https://docs.sparklayer.io/openapi/sync-log.yaml

Returns the sync status for the integration and data type together with its logged errors (at most 5,000). Returns `404` if no full sync has been recorded for them yet.

`GET /api/v1/sync-log/{integration}/{data_type}/errors`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v1/sync-log/shopify/products/errors" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `integration` | string | Yes | The integration the sync log belongs to, such as `shopify`. Logs are kept separately for each integration and data type. Example: `shopify` |
| `data_type` | "products" \| "customers" \| "merchant" \| "purchases" \| "pricing" \| "accountancy" | Yes | The type of data the sync log is for. Example: `products` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: The sync status and its logged errors.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `started_full_sync` | string (date-time) | | Started full sync |
| `last_full_sync` | string (date-time) | | Last full sync |
| `last_full_sync_succeeded` | boolean | | Was the last full sync successful? A successful sync may still have logging errors. A failed full sync may indicate integration configuration issues or timeout. |
| `last_partial_sync` | string (date-time) | | |
| `error_count` | integer | | Sync errors count |
| `errors` | object[] | | |
| `errors[].external_id` | string | | External ID. Length: min 1, max 64. |
| `errors[].external_url` | string | | External URL. Length: min 1, max 1024. |
| `errors[].visible_name` | string | | User friendly name. Length: max 1024. |
| `errors[].api_response` | string | | API response from sync. Length: min 1, max 4294967295. |
| `errors[].friendly_error` | string | | User friendly error. Length: min 1, max 4294967295. |

```json
{
  "started_full_sync": "2023-01-01T01:01:01Z",
  "last_full_sync": "2023-01-01T01:01:01Z",
  "last_full_sync_succeeded": true,
  "last_partial_sync": "2023-01-01T01:01:01Z",
  "error_count": 3,
  "errors": [
    {
      "external_id": "ABC-123",
      "external_url": "https://example.com/products/ABC-123",
      "visible_name": "The ABC 123 Book",
      "api_response": "Error - Product ABC-123 not found",
      "friendly_error": "ABC-123 not found"
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://hub.sparklayer.io/tech-docs"
}
```


---

# Frontend integration guide

URL: https://docs.sparklayer.io/developers/frontend

Install the SparkLayer Frontend: add the Core Script or Shopify app embed, add product page widgets, hide retail elements with data-spark and style with CSS.

The SparkLayer Frontend is what your B2B customers see on your website: their prices, the cart, quick order and their account. Adding it takes a few small code changes to your theme. Once they're in place, B2B customers can log in and start placing orders.

It takes three steps:

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

One script in your theme that loads SparkLayer on every page.

**Step 2.** **Add the product page widgets**

They show each customer their own prices on product pages, and let them add products to an order.

**Step 3.** **Match your design**

CSS variables set the colours, typefaces and spacing, so SparkLayer looks like the rest of your site.

After that, you can tailor the B2B experience further: [Storefront](https://docs.sparklayer.io/help/storefront.md) has the settings, and [Integrations](https://docs.sparklayer.io/help/integrations.md) has advice for each platform.

> **Personalised instructions**
>
> In the SparkLayer Dashboard, **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app gives you personalised instructions for adding the code snippets to your website.

## The SparkLayer Core Script

The Core Script is a JavaScript snippet in your website's theme. It loads the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) your B2B customers use to place orders, manage their account and more.

### Installing the script

**Shopify:**

On Shopify, the **SparkLayer app embed** loads the Core Script for you, so there's no need to edit `theme.liquid` or other theme files.

To enable it:

1. Go to the [Theme setup](https://admin.shopify.com/apps/sparklayer/theme-setup) page in the SparkLayer Shopify app
2. Select your theme from the **Theme** dropdown
3. Click **Enable app embed** - this opens your Shopify theme editor in a new tab
4. In the theme editor, click **Save** in the top right to activate the app embed

The Core Script now loads on your storefront. You can verify it's working by checking the **App Blocks** table on the same page, where the **App Embed** row should show as Enabled.

![Installing the script (Shopify) – Frontend Integration Guide](https://docs.sparklayer.io/images/developers/frontend/frontend-0cfafd.webp)

If you'd prefer not to install SparkLayer yourself, our team can do this for you free of charge. On the Theme setup page, click **Install SparkLayer for me** to request a free install.

**Other platforms:**

Add the SparkLayer Core Script to the `<head>...</head>` of your website's theme so it loads on every page. On BigCommerce, this is typically in `/templates/layout/base.html`.

![Installing the script (Other platforms) – Frontend Integration Guide](https://docs.sparklayer.io/images/shared/frontend-61c96b.webp)

Your customised Core Script is in the SparkLayer Dashboard at **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app.

```html title="Core Script"
<script async src="https://sparkcdn.io/sparkjs/yourstorehere/live"></script>
```

A new installation uses the latest version of the Core Script. You can change the version later (see [Upgrading to the latest version](#upgrading-to-the-latest-version)), and [What's new](https://docs.sparklayer.io/help/whats-new.md) lists the changes in each release.

### Technical details

The Core Script gives SparkLayer the information that controls how it works on your website.

```html title="Core Script with options"
<!-- Copy your own from the SparkLayer Dashboard: Storefront > Widgets -->

<script>
  window.sparkOptions = {
    siteId: "examplestore", // your unique site id
    platform: "shopify", // your platform
    rootUrl: {{ routes.root_url | json }},
    language: {{ request.locale.iso_code | json }},
    accountRedirect: {
      urlRegex: /\/account/g,
      goTo: "/index", // page to redirect logged in users to
    },
    display: {
      stock: {
        show: false, // set to true to show stock level display
        max: 50, // highest stock level to show
        last: 5, // last remaining stock threshold
        low: 15, // low stock threshold
      },
    },
    auth: {
      user: {{ customer.email | json }},
      token: {{ customer.metafields.sparklayer.authentication | json }},
    },
  };
</script>
<script async src="https://sparkcdn.io/sparkjs/yourstorehere/live"></script>
```

This information includes:

| Item | Details |
| --- | --- |
| `siteId` | The website's unique identifier (see [your account and team](https://docs.sparklayer.io/help/dashboard/account.md)) |
| `platform` | The eCommerce platform of the website |
| `language` | The language to be used |
| `accountRedirect` | Where to send logged-in customers who visit a matching URL (`urlRegex`), and the page to send them to (`goTo`) |
| `display` | Which display configurations to enable (see [Storefront](https://docs.sparklayer.io/help/storefront.md)). Since Core Script 2.0, stock display is set per customer group in the Dashboard instead (see [stock display](https://docs.sparklayer.io/help/storefront/stock-display.md)) |
| `auth` | The authentication details of the logged in customer |

### Modifying the core script

The Core Script's options turn specific features on or off and customise how they work.

**Shopify:**

On Shopify, the app embed loads the Core Script for you. To add customisations or configurations, add a small `<script>` block to your theme that defines them.

Add the following to your theme's `theme.liquid` file, just before the closing `</head>` tag:

```html title="theme.liquid"
<script>
  window.sparkOptions = {
    ...window.sparkOptions,
    // Add your customisations here
  };
</script>
```

The `...window.sparkOptions` line keeps any options your theme or another snippet has already set; without it, the new object replaces them.

For example, to set the language and send logged-in customers who visit an account page to your collections page:

```html title="theme.liquid"
<script>
  window.sparkOptions = {
    ...window.sparkOptions,
    language: 'en',
    accountRedirect: {
      urlRegex: /\/account/g,
      goTo: '/collections/all',
    },
  };
</script>
```

The `window.sparkOptions` block must come **before** the SparkLayer app embed loads, so place it in the `<head>` of your theme, not the `<body>` or footer.

**Other platforms:**

On other platforms, `window.sparkOptions` is part of the Core Script you added to your theme's `<head>`. Change the options in that block: see [Technical details](#technical-details) for an example and what each option does, and the [Core Script options](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md) for every option.

For every option, see the [Core Script options](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md). For the settings merchants manage in the Dashboard, see [Storefront](https://docs.sparklayer.io/help/storefront.md).

### Upgrading to the latest version

To upgrade to the latest version of the Core Script, 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 in the SparkLayer Dashboard.

**Step 1.** In the **Upgrade Core Script** section, select the latest numeric version, then click **Save**.

**Step 2.** Update your website so it loads the matching Core Script. If you're not already on version 2, your Core Script looks something like this:

```html title="Version 1 Core Script"
<script async src="https://cdn.sparklayer.io/spark.1.36.x.js"></script>
```

Replace it with the version 2 format:

```html title="Version 2 Core Script"
<script async src="https://sparkcdn.io/sparkjs/<site-id>/<env>"></script>
```

| Item | Details |
| --- | --- |
| `<site-id>` | Your unique Site ID, shown in the SparkLayer Dashboard at **Account** ([open in the SparkLayer Dashboard](https://app.sparklayer.io/settings/account)) |
| `<env>` | The SparkLayer environment: `live`, or `test` if you're using [test mode](https://docs.sparklayer.io/help/dashboard/test-mode.md) |

For example, for a store with Site ID `b2bstore` on the `live` environment:

```html title="Version 2 Core Script"
<script async src="https://sparkcdn.io/sparkjs/b2bstore/live"></script>
```

## Product page widgets

The product page widgets are the parts of SparkLayer B2B customers see on your product and collection pages when they log in. There are three:

**Step 1.** **[Product detail](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md)**

Shown on your product detail pages, it lets customers quickly add products to an order in a table view.

![Product page widgets – Frontend Integration Guide](https://docs.sparklayer.io/images/developers/frontend/frontend-f499d1.webp)

**Step 2.** **[Product card](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md)**

Shown wherever a product card appears, such as a collection page or a product upsell area.

![Product page widgets – Frontend Integration Guide](https://docs.sparklayer.io/images/developers/frontend/frontend-535a99.webp)

**Step 3.** **[Product price](https://docs.sparklayer.io/help/storefront/interfaces/product-price.md)**

Shows a product's B2B price anywhere on your website, such as a product detail page or collection page.

![Product page widgets – Frontend Integration Guide](https://docs.sparklayer.io/images/developers/frontend/frontend-b67dc7.webp)

Adding them takes two steps:

**Step 1.** **Hide the retail elements**

If you're installing SparkLayer on your existing retail website, **hide** the elements B2B customers shouldn't see, such as your retail pricing, add to cart button, variant options and quantity selector. SparkLayer has an attribute you can add to any HTML element to do this (see [Hiding elements](#hiding-elements)).

**Step 2.** **Add the widgets**

Add the SparkLayer code snippets to your product pages, such as the product detail page and collection page. When a B2B customer logs in, the interfaces show automatically, so they can see prices, add items to an order, view their account and check out. See [Storefront widgets](https://docs.sparklayer.io/help/storefront/interfaces.md) for each interface and how to customise it.

### Hiding elements

SparkLayer can hide any element on your website from B2B customers with a `data-spark` attribute.

Elements you would typically hide include:

- Price information
- Product variant information
- Quantity selection
- Buy button

![Hiding elements – Frontend Integration Guide](https://docs.sparklayer.io/images/developers/frontend/frontend-25ee14.webp)

You need access to your website's source code to find the files that contain the elements you want to hide, such as:

- A product detail page
- A product collection page
- Specific "components" that are used in multiple locations on your website

In those files, add `data-spark="b2c-only"` to each element you want to hide. SparkLayer then applies `display: none` to the element when a logged-in B2B customer views the page.

This step changes your website's code, so you may want a developer to help. For platform-specific guidance, see [Integrations](https://docs.sparklayer.io/help/integrations.md).

```html title="Hiding elements from B2B customers"
<div data-spark="b2c-only">
  <!-- Anything inside here will be hidden for B2B customers -->
</div>

<p class="price" data-spark="b2c-only">
  <!-- In this example, the price would be hidden -->
  {{ product.price }}
</p>

<!-- Repeat this process for any HTML element you want hidden -->
```

### Displaying the SparkLayer interfaces

Next, add the SparkLayer [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) to your pages. Each interface's page explains how to add its code snippet.

| Interface | Details |
| --- | --- |
| [Product detail](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) | Shown on your product detail pages; lets customers quickly add products to an order. |
| [Product card](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) | Shown wherever a product card appears, such as a collection page. |
| [Product price](https://docs.sparklayer.io/help/storefront/interfaces/product-price.md) | Shows a product's B2B price anywhere on your website, instead of or alongside the product card. |

## Design customisations (CSS)

SparkLayer's interface is neutral by default, and you can change nearly every aspect of its look and feel with CSS variables, including:

- Colours
- Typography (e.g. typefaces and font sizing)
- Spacing (e.g. padding and margin)
- Button styling
- Form styling

Add the CSS to your existing stylesheets, or to your website's `<head>...</head>` as you did with the Core Script.

![Design customisations (CSS) – Frontend Integration Guide](https://docs.sparklayer.io/images/shared/frontend-e2b840.webp)

### What can be styled

To find the styles you want to change, use your browser's **Inspect element** tool. SparkLayer's styles use CSS variables prefixed with `--spark-`, and you can override each one.

In the inspector, you'll see something like the example below. To change a style, such as a button colour, set the matching variable in your website's CSS. See [Customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md) for details.

```css title="SparkLayer button styles"

.btn, .btn-large, .btn-small {
    color: var(--spark-button-raised-color,var(--spark-lightest-color,#fff));
    background-color: var(--spark-button-raised-background,var(--spark-secondary-color,#125ef8));
    border: var(--spark-button-border,none);
    border-radius: var(--spark-button-radius,var(--spark-border-radius-button,4px));
    padding: var(--spark-button-padding,.875em 1.75em);
    text-transform: var(--spark-button-text-transform,none);
    letter-spacing: var(--spark-button-text-letter-spacing,0);
    font-weight: var(--spark-button-font-weight,400);
    font-family: var(--spark-button-font-family,Poppins,sans-serif);
}
```

## Frontend integration checklist

Before you launch, check you've covered everything:

- **Core Script added.** You've added the SparkLayer Core Script to your website's `<head>`. On Shopify, you've enabled the SparkLayer app embed.
- **Product detail widget added.** You've added the SparkLayer product detail widget to your product detail pages, and hidden content B2B customers shouldn't see, such as your regular direct-to-consumer (DTC) pricing, add to cart buttons, "sticky" content that references pricing, and non-B2B content.
- **Product card widget added.** You've added the SparkLayer product card widget to your product cards (typically on collection and category pages), and hidden DTC pricing, add to cart buttons, "quick buy" buttons and non-B2B content.
- **Every product card checked.** You've checked all areas of your website that show product cards, such as the homepage and product recommendations.
- **CSS and design.** You've added the SparkLayer CSS to your website (in the header or a CSS file) and styled it to match your branding.
- **Cart and cart drawer.** Clicking the cart icon in your website header opens the My Cart interface. If it doesn't, make sure the cart link points to `/cart` and doesn't trigger your theme's JavaScript for B2B customers.
- **General site audit.** You've checked features such as site search and wish lists, so DTC prices are hidden (in CSS or in the code).

## Next steps

- [Storefront widgets](https://docs.sparklayer.io/help/storefront/interfaces.md): add and customise each interface.
- [Core Script options](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md): every `sparkOptions` setting.
- [Technical information](https://docs.sparklayer.io/developers/frontend/technical-information.md): browser support and analytics event tracking.
- [JavaScript SDK](https://docs.sparklayer.io/developers/javascript-sdk.md): build custom or headless interfaces.


---

# Technical information

URL: https://docs.sparklayer.io/developers/frontend/technical-information

How the SparkLayer Frontend loads asynchronously, supported browsers and devices, and how to track B2B events in GA4 or Google Tag Manager via sparkOptions.

SparkLayer is designed to be as lightweight as possible and uses modern JavaScript technology to power the frontend.

## How SparkLayer is loaded

SparkLayer is fully hosted, so there's no code for you to host or maintain.

For performance, the SparkLayer Frontend **only** loads when a customer logs in to your website. The interfaces load asynchronously, so even though SparkLayer is a hosted third-party solution, the impact on page load times is negligible.

## Browser support

SparkLayer supports the latest two versions of these browsers:

- Google Chrome
- Mozilla Firefox
- Apple Safari
- Microsoft Edge
- Apple Safari for iOS
- Google Chrome for Android and iOS

SparkLayer may not work fully with beta or pre-release versions of these browsers.

## Mobile support

The [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) work on desktop, tablet and mobile, so customers can browse your website on any device.

## Building custom interfaces

To build more custom layouts on top of the SparkLayer Frontend, see the [JavaScript SDK](https://docs.sparklayer.io/developers/javascript-sdk.md).

## Event tracking for analytics (Google Analytics, GA4)

SparkLayer can send B2B events, such as add to cart, begin checkout and purchase, to Google Analytics (GA4), Google Tag Manager (GTM) or your own analytics code. You set it up with the `analytics` option in `sparkOptions`, so you'll need a developer to add it to your [Core Script](https://docs.sparklayer.io/developers/frontend.md#modifying-the-core-script).

### Enabling Google Analytics or GTM

Add an `analytics` object with a list of `providers`. Each provider has a `handler` (which analytics tool to send to) and the `events` to send. This example sends every event to GA4, GTM and a custom function:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  analytics: {
    providers: [
      {
        handler: 'ga', // Google Analytics (GA4)
        events: {
          addToCart: true,
          cartUpdate: true,
          shoppingListSave: true,
          shoppingListLoad: true,
          shoppingListDelete: true,
          csvUpload: true,
          quickAdd: true,
          finalStageCheckout: true,
          shippingUpdate: true,
          beginCheckout: true,
          purchase: true,
          viewCart: true,
        },
      },
      {
        handler: 'gtm', // Google Tag Manager
        events: {
          addToCart: true,
          cartUpdate: true,
          shoppingListSave: true,
          shoppingListLoad: true,
          shoppingListDelete: true,
          csvUpload: true,
          quickAdd: true,
          finalStageCheckout: true,
          shippingUpdate: true,
          beginCheckout: true,
          purchase: true,
          viewCart: true,
        },
      },
      {
        handler: function (eventName, eventParam) {
          // Your own analytics code
        },
        events: {
          addToCart: true,
          purchase: true,
        },
      },
    ],
  },
};
```

The `...window.sparkOptions` line keeps the options you've already set; without it, this object replaces them.

### Provider options

| Provider type | Description |
| --- | --- |
| `'ga'` | Integrates with Google Analytics (GA4). This works best with [Shopify's GA4 integration](https://help.shopify.com/en/manual/reports-and-analytics/google-analytics/google-analytics-setup). |
| `'gtm'` | Integrates with Google Tag Manager. |
| function | A custom analytics handler, for other analytics platforms or your own tracking logic. See [Custom analytics provider](#custom-analytics-provider). |

### Available events

| Event name | Description |
| --- | --- |
| `addToCart` | Triggered when a product is added to the cart. |
| `cartUpdate` | Fired when the cart is updated (for example, quantity changes or items removed). |
| `shoppingListSave` | Occurs when a shopping list is saved. |
| `shoppingListLoad` | Occurs when a shopping list is loaded. |
| `shoppingListDelete` | Occurs when a shopping list is deleted. |
| `csvUpload` | Triggered when a CSV file is uploaded. |
| `quickAdd` | Fired during quick add actions. |
| `finalStageCheckout` | Occurs at the final stage of the checkout process. |
| `shippingUpdate` | Fired when shipping details are updated during checkout. |
| `beginCheckout` | Triggered when the checkout process begins. |
| `purchase` | Occurs when a purchase is completed. |
| `viewCart` | Fired when the cart is viewed. |

### Custom analytics provider

To send events to an analytics service SparkLayer doesn't support natively, set `handler` to a function. It receives the event name and its parameters, so you can add any tracking logic:

```javascript title="Custom analytics provider"
{
  handler: function (eventName, eventParam) {
    // Example: send the event to your own analytics endpoint
    fetch('https://your-analytics-endpoint.com/track', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        event: eventName,
        parameters: eventParam,
      }),
    });
  },
  events: {
    addToCart: true,
    cartUpdate: true,
    // ... other events ...
  },
}
```

## Next steps

- [Frontend integration guide](https://docs.sparklayer.io/developers/frontend.md): install the Core Script and product page widgets.
- [Core Script options](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md): every `sparkOptions` setting.
- [Set up the JavaScript SDK](https://docs.sparklayer.io/developers/javascript-sdk/setup.md): customise the frontend with code.


---

# JavaScript SDK

URL: https://docs.sparklayer.io/developers/javascript-sdk

What the SparkLayer JavaScript SDK is, what you can build with it, how it loads with the Core Script, and a first example that fetches a customer's price.

The JavaScript SDK lets your own code work with SparkLayer on your storefront. Your theme can read the same data SparkLayer's own screens use, such as a customer's prices and cart, take the same actions, such as adding to the cart, and run code at key moments, such as just before checkout.

In code, the SDK is the `window.spark` object, which SparkLayer's [Core Script](https://docs.sparklayer.io/help/glossary.md#core-script) adds to every page.

## What you can build

- **Custom pricing displays**: show a customer's price, RRP or price breaks anywhere in your theme. See [Products and pricing](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md).
- **Your own add to cart**: add products, quantities and custom attributes (including files) to the cart. See [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md).
- **Checkout rules**: block checkout with your own validation, such as a product quota checked against your API. See [Checkout](https://docs.sparklayer.io/developers/javascript-sdk/checkout.md).
- **Customer and sales agent tools**: check who's logged in, switch the customer a sales agent orders for, or query their data. See [Customers and accounts](https://docs.sparklayer.io/developers/javascript-sdk/customers-and-accounts.md).
- **Theme integration**: swap variant images, open the cart drawer or send events to your analytics. See [Events and analytics](https://docs.sparklayer.io/developers/javascript-sdk/events-and-analytics.md).
- **Headless storefronts**: load and initialise SparkLayer yourself in a custom frontend. See [Headless and React](https://docs.sparklayer.io/developers/javascript-sdk/headless.md).

### Choose the most stable way to customise

You can build around SparkLayer's own components, and change them too. Prefer the ways that keep working when SparkLayer updates:

1. An **option** or **hook** in the SDK.
2. A [CSS variable](https://docs.sparklayer.io/help/storefront/customising-design.md) for the look, or a [custom slot](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md) to add your own content.
3. Only if neither does the job, change a component's HTML. Keep the change small, and check it after each SparkLayer update.

Planning something bigger? [Talk to our team](https://docs.sparklayer.io/help/support.md) first.

## Build it with AI

Most SDK customisations are a few dozen lines of code, which suits an AI assistant well. Describe what you want, and the prompt below gives your assistant the SDK reference and the rules to follow. Review the code it writes, and test it on an unpublished theme or a test store before it goes live.

For work with the SparkLayer APIs, see [Build with AI](https://docs.sparklayer.io/developers/build-with-ai.md).

## How the SDK loads

The SDK comes with the Core Script, so there's nothing extra to install. On Shopify, the SparkLayer app embed loads it. On other platforms, you add the Core Script to your theme's `<head>` from the SparkLayer Dashboard.

Two rules apply to all SDK code:

- **Set your options first.** You configure the SDK with `window.sparkOptions`, which must be set **before** the Core Script loads.
- **Wait until SparkLayer is ready.** `window.spark` only works once SparkLayer has started, so run your code from the `onReady` hook.

[Set up the SDK](https://docs.sparklayer.io/developers/javascript-sdk/setup.md) covers both in detail.

## Try it: show a customer's price

Add this to your theme's `<head>`, before the Core Script. When SparkLayer is ready, it checks whether a customer is logged in and, if they are, writes their price for one product to the browser console:

```html title="theme.liquid or your theme's <head>"
<script>
  window.sparkOptions = {
    ...window.sparkOptions,
    onReady: async (spark) => {
      if (!(await spark.isLoggedIn())) {
        return;
      }

      // Use a parent product ID and variant SKU from your store
      const pricing = await spark.getPricingForVariant('6660191387839', 'MUG-MOM');
      console.log(pricing.price, pricing.currencyCode, pricing.priceBreaks);
    },
  };
</script>
```

Open a product page as a logged-in B2B customer and check the browser console. The `...window.sparkOptions` line keeps the options already set by the Core Script or other snippets: see [Add your own options and hooks](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#add-your-own-options-and-hooks).

If one of your hooks throws an error, SparkLayer shows a system error with a code such as `OPTIONS:HOOK:OR`. See [Hook error codes](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#hook-error-codes).

## Next steps

- [Set up the SDK](https://docs.sparklayer.io/developers/javascript-sdk/setup.md): Load the Core Script, add your own options and hooks, and wait for SparkLayer to be ready.
- [Products and pricing](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md): Show trade prices, live quantity pricing and the right image for each variant.
- [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md): Add and remove items, set cart fields, attach attributes and files, and open the drawer.
- [Checkout](https://docs.sparklayer.io/developers/javascript-sdk/checkout.md): Block checkout until your own rules are met.
- [Customers and accounts](https://docs.sparklayer.io/developers/javascript-sdk/customers-and-accounts.md): Check the login, work as a sales agent, switch company sections and run GraphQL queries.
- [Events and analytics](https://docs.sparklayer.io/developers/javascript-sdk/events-and-analytics.md): Hooks, DOM events and sending B2B events to Google Analytics or your own tools.
- [Headless and React](https://docs.sparklayer.io/developers/javascript-sdk/headless.md): Load and initialise SparkLayer yourself, with Next.js and React examples.
- [SDK reference](https://docs.sparklayer.io/developers/javascript-sdk/reference.md): Every sparkOptions setting, hook, window\.spark method, type, DOM event and web component.


---

# Set up the SDK

URL: https://docs.sparklayer.io/developers/javascript-sdk/setup

Load the SparkLayer Core Script, add your own sparkOptions and hooks without overwriting others, and wait for SparkLayer to be ready before calling it.

Every SDK customisation starts here: how the SDK loads with the Core Script, how to add your own options and hooks without overwriting anyone else's, and how to wait until SparkLayer is ready. It uses `window.sparkOptions`, the `onReady` hook and, on headless storefronts, `window.initSpark()`.

## How the SDK loads

The SDK comes with the SparkLayer Core Script. On Shopify, the SparkLayer app embed loads it. On other platforms, the Core Script you copy from the SparkLayer Dashboard goes in your theme's `<head>`:

```html title="Core Script"
<script async src="https://sparkcdn.io/sparkjs/<SITE_ID>/live"></script>
```

Replace `<SITE_ID>` with your Site ID, and use `test` instead of `live` in [test mode](https://docs.sparklayer.io/help/dashboard/test-mode.md). The version this URL serves is set in the Dashboard: see [Upgrading to the latest version](https://docs.sparklayer.io/developers/frontend.md#upgrading-to-the-latest-version). For the rest of the storefront setup, see the [frontend integration guide](https://docs.sparklayer.io/developers/frontend.md#the-sparklayer-core-script).

Older themes may load a version 1 file such as `https://cdn.sparklayer.io/spark.1.0.21.js`. These URLs are legacy: replace them with the loader above. Don't use `spark.latest.js` either: it's a legacy bundle that lacks most of the SDK.

When the Core Script runs, it reads `window.sparkOptions`, starts SparkLayer and sets `window.spark`. Your options and hooks must therefore be in place **before** the Core Script loads.

## Add your own options and hooks

Set your options in a `<script>` in the `<head>`, before the Core Script, and always extend the existing object rather than replacing it:

```html title="theme.liquid or your theme's <head>"
<script>
  window.sparkOptions = {
    ...window.sparkOptions,
    language: 'en',
    onCartUpdate: async (cart, results) => {
      // Your code here
    },
  };
</script>
```

`window.sparkOptions = { … }` on its own replaces the whole object, so it wipes anything set earlier: the `siteId` and `auth` in the Core Script on other platforms, or another snippet's hooks. The `...window.sparkOptions` line copies those across first. Every example in these docs extends the existing options, either with this spread or by adding to the object directly.

The spread keeps other settings, but a hook with the same name still replaces the earlier one. If two snippets need the same hook, combine them into one function, or keep a reference to the earlier hook and call it from yours, as the [chained checkout validation](https://docs.sparklayer.io/developers/javascript-sdk/checkout.md#combine-your-rule-with-existing-validation) example does.

For every option and hook, see [Options](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md) and [Hooks](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md) in the SDK reference.

## Wait for SparkLayer to be ready

`window.spark` exists as soon as the Core Script runs, but its data isn't loaded until SparkLayer has started. Run your code from the `onReady` hook, which receives the `Spark` object once SparkLayer has initialised and the page's DOM has loaded. It runs whether or not the customer is logged in, so check with `isLoggedIn()` first:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  onReady: async (spark) => {
    if (!(await spark.isLoggedIn())) {
      return;
    }
    // Safe to call spark methods here
  },
};
```

If your code can run after the Core Script has loaded (for example, from a script at the end of the page or in a separate app), use the `window.sparkReady` promise below instead. It resolves whether SparkLayer started before or after your code.

### Wait for SparkLayer from any script

Add this once, in your theme's `<head>` **before** the SparkLayer Core Script (on Shopify, before the SparkLayer app embed). It resolves `window.sparkReady` with `window.spark` when SparkLayer calls its `onReady` hook, and keeps any `onReady` you already have.

```html title="Theme <head>, before the SparkLayer script"
<script>
  (function () {
    var options = (window.sparkOptions = window.sparkOptions || {});
    var previous = options.onReady;
    var resolveReady;
    window.sparkReady = new Promise(function (resolve) {
      resolveReady = resolve;
    });
    options.onReady = async function (spark) {
      if (previous) await previous(spark);
      resolveReady(spark);
    };
  })();
</script>
```

Then, anywhere after it:

```javascript title="Any script"
const spark = await window.sparkReady;
```

Like the spread above, the snippet adds to `window.sparkOptions` instead of replacing it. Many examples on the other SDK pages start with `await window.sparkReady`, so add this snippet first.

## Manual initialisation (headless only)

On a headless storefront you may want to decide when SparkLayer starts, for example after your app has loaded the customer. If `window.sparkOptions` isn't set when the Core Script runs, SparkLayer doesn't start. Instead it defines `window.initSpark(options)`, which you call yourself:

```html title="Headless storefront"
<script>
  function startSparkLayer() {
    window.spark = window.initSpark({
      siteId: '<SITE_ID>',
      platform: 'shopify',
      auth: { user: 'customer@example.com', token: '<AUTH_TOKEN>' },
      onReady: async (spark) => {
        // SparkLayer is ready
      },
    });
  }
</script>
<script async src="https://sparkcdn.io/sparkjs/<SITE_ID>/live" onload="startSparkLayer()"></script>
```

Pass every option, including hooks, to `initSpark`. Don't set `window.sparkOptions` anywhere on the page (including with the `...window.sparkOptions` pattern), or SparkLayer starts automatically and `initSpark` isn't defined.

That rules out the [`window.sparkReady` snippet](#wait-for-sparklayer) too, because it sets `window.sparkOptions`. Pass an `onReady` hook to `initSpark` instead, and resolve your own promise from it. See [Headless and React](https://docs.sparklayer.io/developers/javascript-sdk/headless.md) for a full example.

## Next steps

- [Products and pricing](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md): Show a customer's price, RRP and price breaks in your own theme code.
- [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md): Add, update and remove items, set cart fields and handle the results of updateCart.
- [SDK reference](https://docs.sparklayer.io/developers/javascript-sdk/reference.md): Every sparkOptions setting, hook, method and type.


---

# Products and pricing

URL: https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing

Show each B2B customer's own price, RRP and price breaks in your theme, price a quantity as it changes, and swap the product image when a variant is selected.

Show B2B prices in your own theme code, work out the price for a quantity, and keep your product images in step with SparkLayer's variant picker. This page uses the pricing methods below and the `spark-variant-change` event.

| Method | Use it to |
| --- | --- |
| [`getPricingForVariant()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getpricingforvariant) | Get a variant's price, RRP and price breaks for the logged-in customer. |
| [`getPriceForProduct()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getpriceforproduct) | Get a product's "from" price across its variants, and how many prices there are. |
| [`calculatePricingForVariant()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#calculatepricingforvariant) | Price a quantity of a variant, including price breaks. |
| [`calculatePricingForVariantData()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#calculatepricingforvariantdata) | Price a quantity from variant data you already have, without a request. |
| [`getPackSizeForVariant()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getpacksizeforvariant) | Get a variant's pack size (`1` if none is set). |
| [`getRrpPriceForVariant()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getrrppriceforvariant) | Get a variant's RRP on its own. |

Each method takes your platform's parent product ID and the variant SKU. Prices are for the logged-in customer, so check `isLoggedIn()` first. Some examples use `window.sparkReady`: add the [Wait for SparkLayer](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#wait-for-sparklayer) snippet before them.

## Calculate the price for a quantity

This example calculates the price of two units of a variant once SparkLayer is ready:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  onReady: async (spark) => {
    if (!(await spark.isLoggedIn())) {
      return;
    }

    // Parent product ID, variant SKU and quantity
    const pricing = await spark.calculatePricingForVariant('6660191387839', 'MUG-MOM', 2);
    console.log(pricing.totalPrice, pricing.unitPrice, pricing.currencyCode);
  },
};
```

`totalPrice` is the quantity × the unit price at that quantity, after any price breaks. See [`ProductVariantPricing`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#productvariantpricing) for every field.

## Show trade prices on your own product tiles

Your theme's collection tiles show retail prices. This swaps in each signed-in B2B customer's own price, with the RRP, and leaves retail visitors' prices alone. Give each tile its product ID and SKU:

```html title="Product tile (Shopify Liquid)"
<div class="tile" data-product-id="{{ product.id }}" data-sku="{{ product.selected_or_first_available_variant.sku }}">
  <span class="tile-price">{{ product.price | money }}</span>
  <span class="tile-rrp"></span>
</div>
```

```javascript title="Trade prices on tiles"
const money = (amount, currency) =>
  new Intl.NumberFormat(document.documentElement.lang || 'en-GB', {
    style: 'currency',
    currency,
  }).format(amount);

async function showTradePrices(root = document) {
  const spark = await window.sparkReady;
  if (!(await spark.isLoggedIn())) return; // retail visitors keep your normal prices

  const tiles = root.querySelectorAll('[data-product-id][data-sku]');
  await Promise.all(
    [...tiles].map(async (tile) => {
      try {
        const { price, rrp, currencyCode } = await spark.getPricingForVariant(
          tile.dataset.productId,
          tile.dataset.sku,
        );
        if (price === null) return; // no B2B price for this customer
        tile.querySelector('.tile-price').textContent = money(price, currencyCode);
        if (rrp) tile.querySelector('.tile-rrp').textContent = `RRP ${money(rrp, currencyCode)}`;
      } catch {
        // the product isn't available to this customer: leave the tile as it is
      }
    }),
  );
}

showTradePrices();
```

Call `showTradePrices(container)` again after your theme loads more products, for example on infinite scroll.

## Read the RRP metafield in Liquid

On Shopify, you can also render the RRP on the server, straight from the variant's `sparklayer.rrp` metafield. The metafield is JSON on the variant, with one entry per currency and decimal values (not subunits), for example `[{"value":9.00,"currency_code":"gbp"}]`. This snippet picks the entry for the shopper's currency, converts it to subunits for Shopify's `money` filter, and only shows it when it differs from the variant's Shopify price:

```liquid title="Product template (Shopify Liquid)"
{%- if customer.metafields.sparklayer.authentication -%}
  {%- assign variant = product.selected_or_first_available_variant -%}
  {%- for entry in variant.metafields.sparklayer.rrp.value -%}
    {%- assign entry_currency = entry.currency_code | upcase -%}
    {%- if entry_currency == cart.currency.iso_code -%}
      {%- assign rrp_subunits = entry.value | times: 100.0 | round -%}
      {%- if rrp_subunits != variant.price -%}
        <span class="b2b-rrp">RRP {{ rrp_subunits | money }}</span>
      {%- endif -%}
      {%- break -%}
    {%- endif -%}
  {%- endfor -%}
{%- endif -%}
```

- Liquid is rendered once, on the server. The RRP doesn't change when the customer picks another variant until the page reloads. For an RRP that follows the selected variant, use [`getRrpPriceForVariant()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getrrppriceforvariant) or the `<spark-product-rrp>` [component](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#web-components).
- Shopify caches pages, so a change to the metafield can take a little while to show.

## Live price as the quantity changes

On a product page with your own quantity box, show the unit price, line total and price-break saving as the customer types, snapped to the product's pack size. It fetches the variant once, then works out each price instantly with `calculatePricingForVariantData`, so there's no request per keystroke.

```html title="Product page"
<input id="b2b-qty" type="number" min="1" value="1" data-product-id="{{ product.id }}" data-sku="{{ product.selected_or_first_available_variant.sku }}" />
<p id="b2b-line-price" aria-live="polite"></p>
```

```javascript title="Live quantity pricing"
const qtyInput = document.querySelector('#b2b-qty');
const output = document.querySelector('#b2b-line-price');
const { productId, sku } = qtyInput.dataset;

const money = (amount, currency) =>
  new Intl.NumberFormat(document.documentElement.lang || 'en-GB', {
    style: 'currency',
    currency,
  }).format(amount);

const spark = await window.sparkReady;
const [variant, packSize] = await Promise.all([
  spark.getVariant(productId, sku),
  spark.getPackSizeForVariant(productId, sku),
]);
qtyInput.step = String(packSize);
qtyInput.min = String(packSize);

function render() {
  // round up to a whole number of packs
  const qty = Math.max(packSize, Math.ceil((Number(qtyInput.value) || 1) / packSize) * packSize);
  const pricing = spark.calculatePricingForVariantData(variant, qty);
  if (pricing.unitPrice === null) {
    output.textContent = 'Price on request';
    return;
  }
  const saving = pricing.priceBreakSavingsPercentage
    ? ` (you save ${pricing.priceBreakSavingsPercentage}%)`
    : '';
  output.textContent = `${qty} × ${money(pricing.unitPrice, pricing.currencyCode)} = ${money(
    pricing.totalPrice,
    pricing.currencyCode,
  )}${saving}`;
}

qtyInput.addEventListener('input', render);
qtyInput.addEventListener('change', () => {
  qtyInput.value = String(Math.ceil((Number(qtyInput.value) || 1) / packSize) * packSize);
  render();
});
render();
```

Load this as a module (`<script type="module">`), so `await` works at the top level.

## Update the product image when a variant is selected

When a customer picks a variant in the `spark-pdp` or `spark-product-card` interface, SparkLayer doesn't change your theme's product image. You can do it with a little theme code:

1. Listen for the `spark-variant-change` event on each `spark-pdp` or `spark-product-card` element.
2. In the listener, show the image for the selected variant and hide the others.

### Listen for the event

`spark-variant-change` is dispatched on the interface element itself and doesn't bubble, so add a listener to each element. Register the listeners in `onReady`, once the elements are on the page:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  onReady: async () => {
    for (const productCard of document.querySelectorAll('spark-product-card')) {
      productCard.addEventListener('spark-variant-change', (event) => {
        console.log(event.detail.product.externalId, event.detail.variant.externalId);
      });
    }
  },
};
```

`event.detail` has:

- `event.detail.product.externalId`: your platform's ID for the product (for example, the Shopify product ID).
- `event.detail.variant.externalId`: your platform's ID for the selected variant.

Elements added to the page later, such as by infinite scroll, need their own listeners.

### Show the variant's image

How you swap images depends on your theme's markup. This approach was tested with Shopify's Dawn theme:

1. Render every variant's image in the product card, for example by looping through the product's variants in the Liquid template. Hide all but the first variant's image, which is selected by default, with `style="opacity: 0"`.
2. Add a `data-variant-id` attribute to each variant image, set to the variant ID.
3. In the listener, hide every variant image in the card and show the one for the selected variant:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  onReady: async () => {
    for (const productCard of document.querySelectorAll('spark-product-card')) {
      productCard.addEventListener('spark-variant-change', (event) => {
        const cardEl = event.target.closest('.card-wrapper');
        if (!cardEl) {
          return;
        }

        const variantId = event.detail.variant.externalId;

        // Hide all variant images
        for (const img of cardEl.querySelectorAll('img[data-variant-id]')) {
          img.style.opacity = '0';
        }

        // Show the selected variant's image
        const variantImg = cardEl.querySelector(`img[data-variant-id="${variantId}"]`);
        if (variantImg) {
          variantImg.style.opacity = '1';
        }
      });
    }
  },
};
```

The same code works for `spark-pdp`: change the selector and the wrapper class to match your product page.

## Next steps

- [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md): Add products to the cart from your own buttons and forms, rounded to pack sizes.
- [Events and analytics](https://docs.sparklayer.io/developers/javascript-sdk/events-and-analytics.md): The hooks and DOM events you can run your own code from.
- [Pricing methods](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#products-and-pricing): Every product and pricing method, and the types they return.


---

# Cart

URL: https://docs.sparklayer.io/developers/javascript-sdk/cart

Add, update and remove cart items with updateCart, set PO numbers and cart fields, attach custom attributes and files, and open the cart drawer from code.

Change the B2B cart from your own code: add, update and remove items, read the cart back, set cart-level fields, attach custom attributes and files, and open the cart drawer. This page uses `updateCart`, `getCart`, `getCartCache`, `uploadFile`, `openDrawer` and `externalClearBasket`, and the `preCartUpdateListener` and `onCartUpdate` hooks.

`window.spark.updateCart` makes every change to the cart. Call it once SparkLayer is ready (see [Wait for SparkLayer to be ready](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#wait-for-sparklayer-to-be-ready)):

```typescript title="Type"
updateCart(
  input: Partial<UpdateCart>,
  cartSuccessHandledLocally?: boolean,
  cartErrorsHandledLocally?: boolean,
): Promise<CartResults[] | null>;
```

The input is an [`UpdateCart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#updatecart) object, and each product in it is a [`CartItemInput`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cartiteminput). Send only the fields you want to change.

## Add, update and remove items

Add a variant by SKU with `adjustQuantity`, which **increments** whatever quantity is already in the cart:

```javascript
await window.spark.updateCart({
  products: [{ sku: 'RED-SHIRT-M', adjustQuantity: 1 }],
});
```

Add several variants in one call:

```javascript
await window.spark.updateCart({
  products: [
    { sku: 'RED-SHIRT-M', adjustQuantity: 2 },
    { sku: 'BLUE-HAT-L', adjustQuantity: 1 },
  ],
});
```

Use `quantity` instead of `adjustQuantity` to **set** the line to an exact quantity rather than add to it, for example from a quantity input on the cart page:

```javascript
await window.spark.updateCart({
  products: [{ sku: 'RED-SHIRT-M', quantity: 5 }],
});
```

### Remove an item or clear the cart

Set `quantity` to `0` to remove a line. If you have the cart line's `itemKey` (from `getCart()`, for example), use it instead of the SKU:

```javascript
await window.spark.updateCart({
  products: [{ itemKey: 'abc123', quantity: 0 }],
});
```

Clear the whole cart:

```javascript
await window.spark.updateCart({ clearCart: true });
```

## Read the cart

`updateCart` returns the result for each line, not the cart. To read the cart, call `getCart()`, which fetches it, or `getCartCache()`, which returns the cached copy without a request (or `null` if there isn't one yet). Both return a [`Cart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cart).

This example adds a product to the cart, sets a custom field on the cart, then reads the cart back:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  onReady: async (spark) => {
    if (!(await spark.isLoggedIn())) {
      return;
    }

    // Add 3 of a variant to the cart
    const results = await spark.updateCart({
      products: [{ sku: 'BRACE-COLOURED', adjustQuantity: 3 }],
    });
    console.log(results); // What was applied to each line

    // Set a custom field on the cart
    await spark.updateCart({
      customFields: [{ name: 'season', value: 'in-season' }],
    });

    console.log(await spark.getCart()); // The updated cart
  },
};
```

## Cart-level fields

Update `customerReference`, `poNumber`, `shippingRequestedDate` and `customFields` the same way, with or without `products`:

```javascript
await window.spark.updateCart({
  customerReference: 'This is a note on the order',
  poNumber: 'PO-4567',
});
```

`customerReference`, `poNumber` and `shippingRequestedDate` hold SparkLayer's standard checkout fields, and `customFields` holds your own.  To show these fields to customers at checkout, see [Checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md) in the Help Center.

## Custom attributes and files

Any product line can carry `customAttributes`: free-form key and value pairs that stay with the line through the cart and into the order, such as engraving text or a fabric choice. The `key` and `value` are shown to the customer and your staff under the line item.

- If you call `updateCart` yourself, such as from your own add-to-cart button, set `customAttributes` on the products you send: see [Add text](#add-text) and [Attach a file](#attach-a-file).
- To add attributes when a customer uses one of SparkLayer's own add-to-cart buttons (in the product detail or product card interface), you don't call `updateCart` yourself: use the [`preCartUpdateListener` hook](#add-attributes-to-sparklayers-add-to-cart) instead.

### Add text

To store text, set `value` to a string:

```javascript
await window.spark.updateCart({
  products: [
    {
      sku: 'SHIRT-CUSTOM',
      adjustQuantity: 1,
      customAttributes: [
        { key: 'Shirt Length', value: '32in' },
        { key: 'Shirt Fabric', value: 'Cotton' },
      ],
    },
  ],
});
```

### Attach a file

To attach a file, use the same array, but set `value` to a JSON string of an array of file GIDs. Upload the file with `spark.uploadFile()` to get its GID:

```javascript
const gid = await window.spark.uploadFile('design.png', fileBlob);

await window.spark.updateCart({
  products: [
    {
      sku: 'SHIRT-CUSTOM',
      adjustQuantity: 1,
      customAttributes: [
        { key: 'Design', value: JSON.stringify([gid]) },
      ],
    },
  ],
});
```

> **Match the file name to the file type**
>
> The file name you pass to `uploadFile()` (`design.png` above) must match the type of the data in `fileData`: don't name a JPEG `design.png`. A mismatch fails a check on the server after upload, the file is deleted, and the GID you got back stops working. Any later lookup of it errors, including reading the cart.

### Add attributes to SparkLayer's add to cart

`preCartUpdateListener` is a hook that runs just before one of SparkLayer's built-in add-to-cart buttons calls `updateCart`. It lets you change the update before it's sent: most often, to add custom attributes or files to the products.

```typescript title="Type"
preCartUpdateListener(input: Partial<UpdateCart>): Promise<Partial<UpdateCart>>;
```

`input` is the update about to be sent to `updateCart` (see [`UpdateCart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#updatecart)), not the current cart: it has no `items` or `totals`, only the products that interface is about to add. Return the update, changed or not, from an `async` function: SparkLayer sends whatever you return.

### Collect customisations from the page

The most common use is to read form fields on the product page and attach their values as `customAttributes` to the products being added. Tag each relevant `input` and `select` with `data-spark-custom-attributes`:

```html title="Product page"
<label for="shirt-length">Shirt Length</label>
<input id="shirt-length" name="Shirt Length" data-spark-custom-attributes />

<label for="shirt-fabric">Shirt Fabric</label>
<select id="shirt-fabric" name="Shirt Fabric" data-spark-custom-attributes>
  <option value="cotton">Cotton</option>
  <option value="polyester">Polyester</option>
</select>
```

Then collect the tagged fields in `preCartUpdateListener`. Each field's label (or its `name`, if it has no label) becomes the attribute's `key`:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  preCartUpdateListener: async (input) => {
    if (!input.products?.length) {
      return input;
    }

    const nodes = document.querySelectorAll(
      'input[data-spark-custom-attributes], select[data-spark-custom-attributes]',
    );

    const handledRadioGroups = new Set();
    const attrs = [];

    nodes.forEach((el) => {
      const type = (el.type || '').toLowerCase();

      if (type === 'radio') {
        if (handledRadioGroups.has(el.name)) return;
        handledRadioGroups.add(el.name);
        el = document.querySelector(
          `input[name="${CSS.escape(el.name)}"][data-spark-custom-attributes]:checked`,
        );
        if (!el) return; // nothing selected in this radio group
      } else if (type === 'checkbox' && !el.checked) {
        return;
      }

      const labelEl = el.id ? document.querySelector(`label[for="${CSS.escape(el.id)}"]`) : null;
      const key =
        labelEl?.textContent.trim().replace(/:$/, '') ||
        el.name;
      const value =
        el.tagName === 'SELECT'
          ? el.options[el.selectedIndex]?.textContent.trim()
          : el.value.trim();

      if (key && value) {
        attrs.push({ key, value });
      }
    });

    if (!attrs.length) {
      return input;
    }

    input.products.forEach((item) => {
      item.customAttributes = [...(item.customAttributes ?? []), ...attrs];
    });

    return input;
  },
};
```

For one or two fixed fields, it's simpler to read them directly:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  preCartUpdateListener: async (input) => {
    if (!input.products?.length) {
      return input;
    }

    const shirtLength = document.querySelector('#shirt-length')?.value;
    const shirtFabric = document.querySelector('#shirt-fabric')?.value;
    if (!shirtLength && !shirtFabric) {
      return input;
    }

    const customShirt = input.products.find((p) => p.sku === 'SHIRT-CUSTOM');
    if (!customShirt) {
      return input;
    }

    customShirt.customAttributes = customShirt.customAttributes ?? [];
    if (shirtLength) {
      customShirt.customAttributes.push({ key: 'Shirt Length', value: shirtLength });
    }
    if (shirtFabric) {
      customShirt.customAttributes.push({ key: 'Shirt Fabric', value: shirtFabric });
    }

    return input;
  },
};
```

### Let customers upload a file

Use the `spark-file-upload-field` web component to let customers upload a file, such as an image or design, on the product page. Then attach it with the same hook.

```html title="Product page"
<spark-file-upload-field
  id="shirt-design-upload"
  allowed-extensions='["png", "jpg", "jpeg"]'
></spark-file-upload-field>
```

| Attribute | Description |
| --- | --- |
| `allowed-extensions` | The file extensions to allow, as a JSON array. Defaults to the most common file extensions. |
| `max-file-size` | Maximum file size, in bytes. |
| `max-files` | Maximum number of files. |
| `required` | Whether a file must be uploaded. |

It dispatches two events, which bubble up to `window`:

- `spark-file-attachment-changed`: whenever the list of files changes. `event.detail` is an array of `{ fileSize, fileName, gid }`, or `null` if every file was removed.
- `spark-file-attachment-failed`: when a file fails to upload.

```javascript title="Listening for upload events"
window.addEventListener('spark-file-attachment-changed', (e) => {
  // e.detail is an array of the file details in the following format:
  // {
  //   fileSize: number,
  //   fileName: string,
  //   gid: string,
  // }

  // Handle files
});

window.addEventListener('spark-file-attachment-failed', (e) => {
  // e.detail format:
  // {
  //   fileSize: number,
  //   fileName: string,
  //   errorCode: string,
  // }
  //
  // errorCode can be one of the following:
  // - "unsupported-file-type"
  // - "file-too-large"
  // - "default"

  // Handle the failed file
});
```

`preCartUpdateListener` and the upload field usually live in different parts of your theme (`sparkOptions` in a layout file, the upload field in a product template), with no shared JavaScript scope. A hidden input is a simple way to pass the uploaded file data between them. Anything works, as long as `preCartUpdateListener` can read it when it runs.

Store the event detail in the hidden input, then use just the `gid`s as the custom attribute's `value`, in the same format as [Attach a file](#attach-a-file):

```html title="Product page"
<!-- holds the uploaded file data, written to and read back below -->
<input id="shirt-design" type="hidden" />

<script>
  {
    const uploadEl = document.querySelector('#shirt-design-upload'); // <-- id of the spark-file-upload-field above
    const inputEl = document.querySelector('#shirt-design');
    if (uploadEl && inputEl) {
      uploadEl.addEventListener('spark-file-attachment-changed', (e) => {
        inputEl.value = e.detail ? JSON.stringify(e.detail) : '';
      });
    }
  }
</script>
```

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  preCartUpdateListener: async (input) => {
    if (!input.products?.length) {
      return input;
    }

    const filesJson = document.querySelector('#shirt-design')?.value; // <-- read back the hidden input from above
    if (!filesJson) {
      return input;
    }

    const gids = JSON.parse(filesJson).map((file) => file.gid);

    const customShirt = input.products.find((p) => p.sku === 'SHIRT-CUSTOM'); // <-- match your own custom-line-item SKU
    if (!customShirt) {
      return input;
    }

    customShirt.customAttributes = [
      ...(customShirt.customAttributes ?? []),
      { key: 'Front Design', value: JSON.stringify(gids) }, // <-- key is shown to the customer/staff as the attachment's label
    ];

    return input;
  },
};
```

### Tag order lines with a campaign

Record which campaign brought a buyer in, as a custom attribute on every line they add, so it shows on the order. It reads `utm_campaign` from the landing page URL and keeps it for the visit. It also calls any `preCartUpdateListener` you already have, so it works alongside the examples above.

```html title="Theme <head>, before the SparkLayer script"
<script>
  (function () {
    var campaign = new URLSearchParams(window.location.search).get('utm_campaign');
    if (campaign) sessionStorage.setItem('b2bCampaign', campaign);

    var options = (window.sparkOptions = window.sparkOptions || {});
    var previous = options.preCartUpdateListener;

    options.preCartUpdateListener = async function (input) {
      var update = previous ? await previous(input) : input;
      var tag = sessionStorage.getItem('b2bCampaign');
      if (!tag || !update.products) return update;

      update.products = update.products.map(function (product) {
        return Object.assign({}, product, {
          customAttributes: (product.customAttributes || []).concat([{ key: 'Campaign', value: tag }]),
        });
      });
      return update;
    };
  })();
</script>
```

## Open the cart drawer

`openDrawer()` opens the SparkLayer drawer, on the Cart tab unless you pass another [tab](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#draweruistate). To open it each time the cart changes, call it from the `onCartUpdate` hook. This example also switches a drawer that's already open to the Cart tab:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  onCartUpdate: async (cart, results) => {
    // Opens the drawer if it isn't already open
    window.spark.openDrawer('cart');

    // Switches an open drawer to the Cart tab
    window.dispatchEvent(
      new CustomEvent('view-update', {
        bubbles: true,
        composed: true,
        detail: { view: 'cart' },
      }),
    );
  },
};
```

## Handle the result and show feedback

### What updateCart returns

`updateCart` resolves to an array of [`CartResults`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cartresults), one for each product line you sent, or `null` if the request failed. It doesn't throw: on failure it shows an error toast and logs the error to the console.

Each result has:

- `requestedQuantity` and `resultantQuantity`: what you asked for and what was applied. They differ when one of the `messages` below applies, such as rounding to a pack size or limiting to the stock available.
- `itemKey`, `sku` and `name`: which line the result is for.
- `messages`: a list of `{ type }` objects for anything that happened to the line. `type` is one of:

| Type | Meaning |
| --- | --- |
| `success` | The line was added or updated with no issues. |
| `pack-size` | The quantity was rounded down to the nearest pack size. |
| `qty-excessive` | The quantity was lowered to the allowed maximum. |
| `qty-insufficient` | The quantity was raised to the allowed minimum. |
| `qty-unavailable` | The quantity was lowered to what's in stock. |
| `qty-unavailable-no-clamp` | The line was added, but the requested quantity isn't fully available. Check the cart. |
| `excessive-lines` | The cart's line limit was reached, so the item wasn't added. |
| `not-found` | The SKU doesn't exist. |
| `unavailable` | The product can't be bought at the moment. |
| `product-settings-overridden` | The product's default settings were overridden. |

These are status codes, not display text. `updateCart` uses them to show its own toasts (see below). If you show your own messages, switch on `type`.

### Show your own feedback

By default, `updateCart` shows toast messages. Pass `true` as the second argument (`cartSuccessHandledLocally`) to turn off the success toast, or as the third (`cartErrorsHandledLocally`) to turn off toasts for the `messages` in the results:

```javascript
// Suppress the built-in success toast, but keep automatic error toasts
await window.spark.updateCart(
  { products: [{ sku: 'RED-SHIRT-M', adjustQuantity: 1 }] },
  true, // cartSuccessHandledLocally
);
```

## Add to cart from your own button

Add a product to the B2B cart from any button, rounded up to its pack size, then open the cart drawer. SparkLayer shows its own messages if the quantity is changed, for example to match the stock available. This uses `window.sparkReady` from [Wait for SparkLayer](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#wait-for-sparklayer).

```html title="Any page"
<button type="button" data-add-to-trade-order data-product-id="{{ product.id }}" data-sku="{{ product.selected_or_first_available_variant.sku }}" data-qty="12">
  Add 12 to order
</button>
```

```javascript title="Add to cart"
document.addEventListener('click', async (event) => {
  const button = event.target.closest('[data-add-to-trade-order]');
  if (!button) return;

  const spark = await window.sparkReady;
  const { productId, sku } = button.dataset;
  const packSize = await spark.getPackSizeForVariant(productId, sku);
  const quantity = Math.ceil(Number(button.dataset.qty || 1) / packSize) * packSize;

  button.disabled = true;
  try {
    const results = await spark.updateCart({ products: [{ sku, adjustQuantity: quantity }] });
    if (results) spark.openDrawer('cart'); // null means SparkLayer already showed an error
  } finally {
    button.disabled = false;
  }
});
```

The click listener sits on `document`, so it also works for buttons your theme adds later.

## Quick order from a pasted list

Let buyers paste a list of SKUs and quantities, one per line, such as `MUG-BLUE 24` or `MUG-BLUE,24`, and add everything in one update. Duplicate SKUs are added together.

```html title="Quick order form"
<form id="quick-order">
  <label for="quick-order-lines">SKUs and quantities, one per line</label>
  <textarea id="quick-order-lines" rows="8" placeholder="MUG-BLUE 24&#10;MUG-RED, 12"></textarea>
  <button type="submit">Add to order</button>
  <p id="quick-order-result" aria-live="polite"></p>
</form>
```

```javascript title="Quick order"
document.querySelector('#quick-order').addEventListener('submit', async (event) => {
  event.preventDefault();
  const text = document.querySelector('#quick-order-lines').value;
  const result = document.querySelector('#quick-order-result');

  const totals = new Map();
  const skipped = [];
  for (const line of text.split('\n').map((l) => l.trim()).filter(Boolean)) {
    const [sku, qty] = line.split(/[\s,;\t]+/);
    const quantity = Number.parseInt(qty ?? '1', 10);
    if (!sku || !Number.isFinite(quantity) || quantity < 1) {
      skipped.push(line);
      continue;
    }
    totals.set(sku, (totals.get(sku) ?? 0) + quantity);
  }
  if (!totals.size) {
    result.textContent = 'Add at least one SKU and quantity.';
    return;
  }

  const spark = await window.sparkReady;
  const products = [...totals].map(([sku, adjustQuantity]) => ({ sku, adjustQuantity }));
  const results = await spark.updateCart({ products });
  if (!results) return; // SparkLayer showed the error

  const added = results.filter((r) => r.resultantQuantity > 0).length;
  result.textContent = `Added ${added} of ${products.length} products.${
    skipped.length ? ` Couldn't read: ${skipped.join(', ')}.` : ''
  }`;
  spark.openDrawer('cart');
});
```

## Clear the cart after an order

If customers complete orders outside SparkLayer's checkout and your order confirmation page loads the Core Script, clear their B2B cart there:

```javascript title="Order confirmation page"
const spark = await window.sparkReady;
await spark.externalClearBasket();
```

## Next steps

- [Checkout](https://docs.sparklayer.io/developers/javascript-sdk/checkout.md): Check the cart against your own rules before the customer can check out.
- [Products and pricing](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md): Show trade prices and live quantity pricing in your theme.
- [Cart types](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cart): The UpdateCart, CartItemInput, CartResults and Cart types in full.


---

# Checkout

URL: https://docs.sparklayer.io/developers/javascript-sdk/checkout

Block SparkLayer checkout until your own rules are met with the onCheckoutValidation hook, from a simple product quota check to rules chained together.

Add your own rules to SparkLayer's checkout, for rules SparkLayer's own settings don't cover. This page uses the `onCheckoutValidation` hook, with examples that call your own API and that combine several rules.

## Add custom checkout validation

`onCheckoutValidation` lets you check the cart against your own rules, or your own API, before the customer can check out. For example, you could check whether a customer has already used up a one-off discount or a product quota, or limit how many free samples go in one order.

The hook must be an `async` function. It receives the [`Cart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cart) and the current checkout step (a [`CartUIState`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cartuistate), so your rules can vary by step), and returns `null` if the cart is valid or an array of `{ message }` objects if it isn't.

SparkLayer shows each `message` to the customer and won't let them check out until the hook returns `null`.  The hook runs every time the cart loads or changes, so keep it quick: avoid network requests unless your rule needs them, and keep any you make fast.

### Check the cart against your API

This example sends the cart to your own endpoint and blocks checkout if it says the cart isn't valid:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  onCheckoutValidation: async (cart, cartUiState) => {
    const response = await fetch('https://example.com/cart-validation', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(cart),
    });
    const { valid } = await response.json();

    if (valid) {
      return null;
    }

    return [{ message: 'This order is over your quota for one of these products.' }];
  },
};
```

Decide what should happen if your API is unreachable. Here, a failed request rejects the promise: SparkLayer logs the error to the console and doesn't apply a result.

### Combine your rule with existing validation

Setting `onCheckoutValidation` replaces any hook another snippet has set. To add a rule without losing one that's already there, keep a reference to the earlier hook, call it, and add your messages to its list. This example limits free samples to three per order:

```html title="Theme <head>, before the SparkLayer script"
<script>
  (function () {
    var options = (window.sparkOptions = window.sparkOptions || {});
    var previous = options.onCheckoutValidation;

    options.onCheckoutValidation = async function (cart, cartUiState) {
      var errors = (previous && (await previous(cart, cartUiState))) || [];

      var samples = cart.items
        .filter(function (item) {
          return item.sku && item.sku.indexOf('SAMPLE-') === 0;
        })
        .reduce(function (total, item) {
          return total + item.quantity;
        }, 0);

      if (samples > 3) {
        errors.push({
          message: 'You can order up to 3 samples per order. Remove ' + (samples - 3) + ' to continue.',
        });
      }
      return errors.length ? errors : null;
    };
  })();
</script>
```

## Collect extra details at checkout

To ask customers for a PO number, a requested delivery date or your own fields at checkout, turn on [checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md) in the Help Center, or set them in code with the [`checkoutCustomElements`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#checkout-and-account) option. To fill these values in from your own code, see [Cart-level fields](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#cart-level-fields).

## Next steps

- [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md): Add and remove items, set cart-level fields and handle the results of updateCart.
- [Checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md): Turn on standard checkout fields and add your own.
- [onCheckoutValidation](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncheckoutvalidation): The hook's signature and return value, with links to the Cart and CartUIState types.


---

# Customers and accounts

URL: https://docs.sparklayer.io/developers/javascript-sdk/customers-and-accounts

Check whether a B2B customer is logged in, switch customers as a sales agent, change company section, refresh customer data and run GraphQL queries.

Work with the logged-in customer from your own code: check the login, act for a customer as a sales agent, switch company section, refresh their data and query the GraphQL API. This page uses `isLoggedIn`, `switchImpersonatingCustomer`, `setActiveCompanySection`, `refreshGlobalData`, `getActiveCustomerVerificationToken` and `fetch`, plus the `spark-redirect.js` login redirect.

The examples use `window.sparkReady`: add the [Wait for SparkLayer](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#wait-for-sparklayer) snippet before them. For every method's parameters and return values, see [Customers and session](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#customers-and-session) in the SDK methods.

## Check whether the customer is logged in

`isLoggedIn()` resolves to `true` when the customer is logged in to SparkLayer. The `onReady` hook runs for every visitor, so check it before you show B2B content or call pricing and cart methods:

```javascript title="Any script"
const spark = await window.sparkReady;

if (await spark.isLoggedIn()) {
  // Show B2B content
}
```

## Switch the customer a sales agent orders for

A [sales agent](https://docs.sparklayer.io/help/sales-reps.md) can order on behalf of their customers. `switchImpersonatingCustomer()` changes the customer they're acting for, and `null` ends impersonation. Both resolve to the [`UserData`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#userdata) for the active customer, or `null`.

```javascript title="Any script"
const spark = await window.sparkReady;

// Act for a customer
const customer = await spark.switchImpersonatingCustomer('<CUSTOMER_ID>');

// End impersonation
await spark.switchImpersonatingCustomer(null);
```

While a sales agent is impersonating, pass `true` as the `useImpersonatingCustomer` argument of [`fetch()`](#run-a-graphql-query) to run a query as the impersonated customer rather than the sales agent.

## Select a company section

If a customer's company is split into sections, `setActiveCompanySection()` selects the one they're buying for. If the cart isn't empty, the customer is asked to confirm and the cart is cleared, then the page reloads. It resolves to `false` if the section isn't available to the customer, they cancel, or the cart couldn't be cleared.

```javascript title="Any script"
const spark = await window.sparkReady;
const user = await spark.refreshGlobalData();
const section = user?.companySections[0];

if (section && !(await spark.setActiveCompanySection(section.id))) {
  // The section wasn't changed
}
```

## Refresh customer and site data

SparkLayer caches the active customer and the site configuration. If they change while the page is open, for example after your own code updates the customer through the API, call `refreshGlobalData()` to fetch them again. It resolves to the active customer's [`UserData`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#userdata), or `null`.

```javascript title="Any script"
const spark = await window.sparkReady;
const user = await spark.refreshGlobalData();
```

## Get a customer verification token

`getActiveCustomerVerificationToken()` refetches the active customer and resolves to a fresh form customer verification token, or `null`. When a sales agent is impersonating, the token is for the impersonated customer; otherwise it's for the logged-in customer.

```javascript title="Any script"
const spark = await window.sparkReady;
const token = await spark.getActiveCustomerVerificationToken();
```

## Run a GraphQL query

`spark.fetch` runs a GraphQL query as the signed-in customer. This one reads their email address:

```javascript title="GraphQL query"
const spark = await window.sparkReady;
const response = await spark.fetch(`query {
  loggedInCustomer {
    id
    email
  }
}`);

if (response.status === 200) {
  const { data, errors } = await response.json();
  if (!errors?.length) console.log(data.loggedInCustomer.email);
}
```

`fetch` returns a standard `Response`: check `status`, then call `json()` for the `data` and `errors`. See [fetch()](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#fetch) for its other arguments.

## Redirect to the login page

`spark-redirect.js` sends customers who aren't logged in to your login page when they follow a link that needs SparkLayer, such as the **View order** button in some emails. This lets SparkLayer open what the link was for once they've logged in.

Add it to your theme in addition to the Core Script. On Shopify, put it outside the `{%- if customer.metafields.sparklayer.authentication -%}` block, so it loads for customers who aren't logged in:

```html title="theme.liquid"
<script async src="https://cdn.sparklayer.io/spark-redirect.js"></script>
```

By default, customers are sent to `/account/login`. To use another path, set `window.sparkRedirectLoginPath` before the script:

```html title="theme.liquid"
<script>
  window.sparkRedirectLoginPath = '/account/login';
</script>
<script async src="https://cdn.sparklayer.io/spark-redirect.js"></script>
```

## Next steps

- [Events and analytics](https://docs.sparklayer.io/developers/javascript-sdk/events-and-analytics.md): Run your code when the customer logs out, the cart changes or SparkLayer is ready.
- [Sales rep setup](https://docs.sparklayer.io/help/sales-reps.md): Add sales agents and choose which customers they can order for.
- [Customer methods](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#customers-and-session): Every customer and session method, and the UserData type.


---

# Events and analytics

URL: https://docs.sparklayer.io/developers/javascript-sdk/events-and-analytics

Run your own code from SparkLayer's hooks and DOM events, send B2B events to Google Analytics or Tag Manager, and push cart changes to any analytics tool.

Run your own code at key moments in SparkLayer, react to what customers do in its interfaces, and send B2B events to your analytics. This page covers the `onLoad`, `onReady`, `onCartLoad`, `onCartUpdate` and `onLogout` hooks, SparkLayer's DOM events and web components, and the `analytics` option.

## Hooks

Hooks are `async` functions you set on `window.sparkOptions` before the Core Script loads (see [Add your own options and hooks](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#add-your-own-options-and-hooks)). SparkLayer calls them at these points:

| Hook | When it runs | Receives |
| --- | --- | --- |
| [`onLoad`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onload) | Once while SparkLayer initialises, after translations have loaded and before `onReady`, whether or not the customer is logged in. | The `Spark` object |
| [`onReady`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onready) | When SparkLayer has initialised and the page's DOM has loaded. The place to start most of your code. | The `Spark` object |
| [`onCartLoad`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncartload) | When the cart is loaded. | The `Cart` |
| [`onCartUpdate`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncartupdate) | Each time the cart is updated. | The updated `Cart` and the `CartResults` for each change |
| [`onLogout`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onlogout) | When the customer logs out. | Nothing |

Two more hooks change what SparkLayer does rather than react to it: `preCartUpdateListener` edits an update before SparkLayer's add to cart sends it (see [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#add-attributes-to-sparklayers-add-to-cart)), and `onCheckoutValidation` blocks checkout (see [Checkout](https://docs.sparklayer.io/developers/javascript-sdk/checkout.md)).

If `onReady`, `onCartLoad` or `onCartUpdate` throws an error, SparkLayer shows a system error with a code that names the hook. See [Hook error codes](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#hook-error-codes).

## DOM events and web components

SparkLayer's interfaces are web components, such as `<spark-pdp>` and `<spark-product-card>`, that you add to your theme. Some of them dispatch DOM events you can listen for:

- `spark-variant-change`: the customer selects a variant in `spark-pdp` or `spark-product-card`. It doesn't bubble, so listen on each element. See [Update the product image when a variant is selected](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md#update-the-product-image-when-a-variant-is-selected).
- `spark-file-attachment-changed` and `spark-file-attachment-failed`: a file is added to, removed from or fails to upload to a `spark-file-upload-field`. See [Let customers upload a file](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#let-customers-upload-a-file).
- `view-update`: you dispatch this one on `window` to switch an open drawer to a tab. See [Open the cart drawer](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#open-the-cart-drawer).

For every web component and event, with the shape of each `event.detail`, see [Events and components](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md) in the SDK reference.

## Google Analytics

SparkLayer can send B2B events, such as add to cart, begin checkout and purchase, to Google Analytics (GA4), Google Tag Manager or your own function. You turn this on with the `analytics` option in `sparkOptions`, listing a `handler` and the `events` to send for each provider.

For the configuration, the list of events and a custom handler example, see [Event tracking for analytics](https://docs.sparklayer.io/developers/frontend/technical-information.md#event-tracking-for-analytics-google-analytics-ga4).

## Send cart changes to your analytics

For tools other than [Google Analytics](#google-analytics), push cart changes to the data layer from the `onCartUpdate` hook. This snippet keeps any `onCartUpdate` you already have:

```html title="Theme <head>, before the SparkLayer script"
<script>
  (function () {
    var options = (window.sparkOptions = window.sparkOptions || {});
    var previous = options.onCartUpdate;

    options.onCartUpdate = async function (cart, results) {
      if (previous) await previous(cart, results);
      window.dataLayer = window.dataLayer || [];
      (results || []).forEach(function (result) {
        window.dataLayer.push({
          event: 'b2b_cart_change',
          sku: result.sku,
          name: result.name,
          quantity: result.resultantQuantity,
          currency: cart.currencyCode,
        });
      });
    };
  })();
</script>
```

## Next steps

- [Event tracking for analytics](https://docs.sparklayer.io/developers/frontend/technical-information.md#event-tracking-for-analytics-google-analytics-ga4): Turn on GA4 or Google Tag Manager, and see every event SparkLayer sends.
- [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md): Change the cart from your own code and open the cart drawer.
- [Hooks](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md): When each hook runs, what it receives and returns, with an example of each.


---

# Headless and React

URL: https://docs.sparklayer.io/developers/javascript-sdk/headless

Run SparkLayer on a headless storefront: load the Core Script, start it with initSpark, authenticate the customer, and use it from Next.js and React.

On a headless storefront, your own frontend renders the pages, so it also loads SparkLayer: it fetches the logged-in customer, loads the Core Script and starts SparkLayer with `window.initSpark()`. This page walks through a headless Shopify storefront built with Next.js, using `window.initSpark()` and the `onReady` and `onLogout` options, then shows a React hook for calling `window.spark` from your components.

SparkLayer still needs your platform's data (products, customers and orders) to stay in sync. On Shopify, the SparkLayer app does this. For another platform or a custom backend, [SparkLayer Ignite](https://docs.sparklayer.io/ignite.md) connects it to SparkLayer. 

## Requirements

- **A Shopify store** with the [SparkLayer app](https://apps.shopify.com/sparklayer) installed.
- **A metafield definition** for the SparkLayer authentication customer metafield (`sparklayer.authentication`).
- **Storefront access** turned on for that metafield definition, so your frontend can read it.

SparkLayer stores each customer's authentication data in this metafield. Your frontend passes it to SparkLayer, which uses it to authenticate the customer with the SparkLayer API.

## How it works

1. Get the logged-in customer's data.
2. Check that they're a B2B customer (in this example, tagged `b2b`) and have the `sparklayer.authentication` metafield set. If not, don't load SparkLayer.
3. Load the Core Script by adding a script tag: `<script async src="https://sparkcdn.io/sparkjs/<SITE_ID>/live"></script>`.
4. Once the script has loaded, call `window.initSpark({ … })` with your options, such as `siteId`, `platform` and `auth`. See [Options](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md).
5. Add a `<style>` element that sets SparkLayer's CSS variables, to match the interfaces to your design. See [Customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md).

Don't set `window.sparkOptions` on a headless site. If it's set when the Core Script runs, SparkLayer starts automatically and `window.initSpark` isn't defined.

You'll also need to add SparkLayer's interfaces, hide elements B2B customers shouldn't see, and connect SparkLayer to controls on your site, such as the cart and account buttons.

## Hide elements from B2B customers

Hide these elements from B2B customers on every page:

- Prices
- Add to cart buttons
- Quantity selectors

Add `data-spark="b2c-only"` to an element and SparkLayer hides it once it loads for a B2B customer. See [Hiding elements](https://docs.sparklayer.io/developers/frontend.md#hiding-elements).

## Add SparkLayer's interfaces

Add SparkLayer's interfaces in place of the elements you've hidden. How you output the parent product ID depends on your templating system; the examples below use a `{{ parentProductId }}` placeholder.

### Product card

```html title="Product list"
<spark-product-card parent-id="{{ parentProductId }}"></spark-product-card>
```

See [Product card](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) for its settings.

### Product detail page

```html title="Product detail page"
<spark-pdp parent-id="{{ parentProductId }}"></spark-pdp>
```

See [Product detail](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) for its settings.

## Load SparkLayer in Next.js

This React component loads SparkLayer in a Next.js project. It adds the Core Script only for B2B customers, then calls `initSpark` once the script has loaded and the authentication metafield is available:

```jsx title="SparkLayer.jsx"
import { useState, useEffect } from 'react';
import Script from 'next/script';

const defaultStyles = `
/* Size SparkLayer's web components to fit your design */
spark-product-card {
  width: 100%;
}
spark-pdp {
  margin: 0.5em 0 1.25em;
  display: block;
}

/* Set CSS variables to style the elements inside SparkLayer's web components */
:root {
  --b2b-brand-color: var(--primary);             /* Main brand colour */
  --b2b-brand-color-hover: var(--secondary);     /* Main brand colour on hover */
  --b2b-brand-font: Poppins, sans-serif;         /* Main brand font */
  --b2b-brand-font-heading: Poppins, sans-serif; /* Main brand heading font */

  /* For more variables, see https://docs.sparklayer.io/help/storefront/customising-design */
}`;

const defaultOptions = {
  platform: 'shopify',
  shopify: {
    useAppProxy: false,
  },
  cartButtonSelectors: '', // CSS selector for the cart button, usually in the header
  accountButtonSelectors: '', // CSS selector for the account button, usually in the header
};

export function SparkLayer(props) {
  const {
    customer,
    authenticationMetafield,
    options,
    onLogout,
    styles = defaultStyles,
  } = props;

  const sparkOptions = { ...defaultOptions, ...options };

  const [sparkInitialised, setSparkInitialised] = useState(false);
  const [sparkLoaded, setSparkLoaded] = useState(false);

  useEffect(() => {
    if (
      !sparkInitialised &&
      customer !== null &&
      authenticationMetafield.finished &&
      sparkLoaded &&
      !window.spark
    ) {
      const style = document.createElement('style');
      style.textContent = styles;
      document.head.appendChild(style);

      window.spark = window.initSpark({
        ...sparkOptions,
        onLogout,
        auth: {
          user: customer?.email,
          token: authenticationMetafield.metafield?.value,
        },
      });
      setSparkInitialised(true);
    }
  }, [customer, authenticationMetafield, sparkLoaded]);

  return customer !== null && customer.tags.includes('b2b') ? (
    <Script
      id="spark-script"
      src={`https://sparkcdn.io/sparkjs/${sparkOptions.siteId}/live`}
      onLoad={() => {
        setSparkLoaded(true);
      }}
    />
  ) : null;
}
```

Use the component in your layout, passing in the customer and their authentication metafield:

```jsx title="Layout.jsx"
import { SparkLayer } from '../snippets/Integrations/SparkLayer';

function Layout({ children }) {
  // Your app provides the logged-in customer's data
  const customer = getCustomer();

  // Your app provides the logged-in customer's Shopify metafields
  const authenticationMetafield = getCustomerMetafield('sparklayer.authentication');

  return (
    <div>
      <SparkLayer
        options={{
          siteId: '<SITE_ID>',
        }}
        onLogout={() => {
          // Log the customer out with your app's own function
          logout();
        }}
        authenticationMetafield={authenticationMetafield}
        customer={customer}
      />
      {children}
    </div>
  );
}

export default Layout;
```

If your app renders pages on the client, your cart and account buttons may lose SparkLayer's click handlers when your header re-renders. Open the drawer from your own buttons instead, with [`openDrawer()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#opendrawer), for example `window.spark.openDrawer('account')`.

To talk through a headless build with our team, [get in touch](https://docs.sparklayer.io/help/support.md).

## Use SparkLayer in React

A small hook that waits for SparkLayer and re-renders once it's ready. It's safe with server rendering, because it only touches `window` in an effect.

```tsx title="useSpark.ts"
import { useEffect, useState } from 'react';

// Spark is the type from spark.d.ts: /developers/javascript-sdk/reference/types#spark
declare global {
  interface Window {
    sparkReady?: Promise<Spark>;
  }
}

export function useSpark(): Spark | null {
  const [spark, setSpark] = useState<Spark | null>(null);

  useEffect(() => {
    let active = true;
    window.sparkReady?.then((ready) => {
      if (active) setSpark(ready);
    });
    return () => {
      active = false;
    };
  }, []);

  return spark;
}
```

```tsx title="TradePrice.tsx"
import { useEffect, useState } from 'react';
import { useSpark } from './useSpark';

export function TradePrice({ productId, sku }: { productId: string; sku: string }) {
  const spark = useSpark();
  const [label, setLabel] = useState<string | null>(null);

  useEffect(() => {
    if (!spark) return;
    spark
      .getPricingForVariant(productId, sku)
      .then(({ price, currencyCode }) => {
        if (price === null) return;
        setLabel(new Intl.NumberFormat(undefined, { style: 'currency', currency: currencyCode }).format(price));
      })
      .catch(() => setLabel(null));
  }, [spark, productId, sku]);

  return label ? <span className="trade-price">{label}</span> : null;
}
```

The hook reads `window.sparkReady`, so something must create that promise before your components render:

- If SparkLayer starts on its own (with `window.sparkOptions`), add the [Wait for SparkLayer](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#wait-for-sparklayer) snippet before the SparkLayer script, for example in your root layout's `<head>`.
- If you start SparkLayer with `initSpark`, as in the Next.js example above, don't use that snippet: it sets `window.sparkOptions`. Create `window.sparkReady` yourself before your components render, and resolve it from the `onReady` option you pass to `initSpark`.

## Next steps

- [Set up the SDK](https://docs.sparklayer.io/developers/javascript-sdk/setup.md): How the SDK loads, how to wait for it to be ready, and manual initialisation.
- [SDK reference](https://docs.sparklayer.io/developers/javascript-sdk/reference.md): Every option you can pass to initSpark, plus each hook, method and type.
- [Frontend integration](https://docs.sparklayer.io/developers/frontend.md): The Core Script, the product page interfaces and hiding elements from B2B customers.


---

# SDK reference

URL: https://docs.sparklayer.io/developers/javascript-sdk/reference

Look up every sparkOptions setting, hook, window.spark method, DOM event and web component in the SparkLayer JavaScript SDK, and download its types.

You set [`window.sparkOptions`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md) before the Core Script loads, and SparkLayer then sets [`window.spark`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md), the object with every method. On a [headless storefront](https://docs.sparklayer.io/developers/javascript-sdk/headless.md), leave `window.sparkOptions` unset and call `window.initSpark(options)` yourself: it takes the same options and returns the same object.

For worked examples, start with [Set up the SDK](https://docs.sparklayer.io/developers/javascript-sdk/setup.md).

## Options

The settings on `window.sparkOptions`. Only `siteId` is required.

**Site and platform**

| Option | What it does |
| --- | --- |
| [`siteId`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#site-and-platform) | Your site ID. Required. |
| [`sparkDomain`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#site-and-platform) | The domain of the SparkLayer API. |
| [`platform`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#site-and-platform) | Sets the default options for your ecommerce platform. |
| [`rootUrl`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#site-and-platform) | Prefixes the URLs SparkLayer creates, generally for i18n. |
| [`wordpressSiteUrl`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#site-and-platform) | The WordPress site URL, on WooCommerce. |
| [`shopify`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#site-and-platform) | Shopify options: whether to use the app proxy. |
| [`bigcommerce`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#site-and-platform) | BigCommerce options: your app client ID. |

**Links and redirects**

| Option | What it does |
| --- | --- |
| [`accountRedirect`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#links-and-redirects) | Sends logged-in users from matching paths to a page with the account drawer open. |
| [`cartRedirect`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#links-and-redirects) | Sends logged-in users from matching paths to a page with the cart drawer open. |
| [`termsAndConditionsLink`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#links-and-redirects) | Link to your terms and conditions. |
| [`productLink`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#links-and-redirects) | The link to a product page, built from the product's slug. |

**Button selectors**

| Option | What it does |
| --- | --- |
| [`accountButtonSelectors`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#button-selectors) | CSS selectors for the account button. |
| [`logoutButtonSelectors`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#button-selectors) | CSS selectors for the logout button. |
| [`cartButtonSelectors`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#button-selectors) | CSS selectors for the cart button. |
| [`loginButtonSelectors`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#button-selectors) | CSS selectors for the login button. |

**Display, language and translations**

| Option | What it does |
| --- | --- |
| [`display`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#display-language-and-translations) | Display options, such as the dark theme, SKUs and My Account sections. |
| [`language`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#display-language-and-translations) | The language SparkLayer uses. |
| [`locale`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#display-language-and-translations) | The locale for formatting dates. |
| [`translations`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#display-language-and-translations) | Overrides SparkLayer's text, by language. |
| [`showTranslations`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#display-language-and-translations) | Shows translation keys instead of text, for debugging. |

**Checkout and account**

| Option | What it does |
| --- | --- |
| [`checkoutCustomElements`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#checkout-and-account) | Standard and custom fields to show in checkout. |
| [`paymentMethodsOrder`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#checkout-and-account) | The order of the payment methods. |
| [`saveToAddressBookDefault`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#checkout-and-account) | Whether new addresses are saved to the address book by default. |
| [`customAccountDetails`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#checkout-and-account) | Extra details to show on a customer's My Details panel. |
| [`igniteCheckoutContext`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#checkout-and-account) | Checkout context data to pass to Ignite. |

**Authentication and analytics**

| Option | What it does |
| --- | --- |
| [`auth`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#authentication-and-analytics) | The user and token for SparkLayer auth. |
| [`authLogoutUri`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#authentication-and-analytics) | Where SparkLayer redirects after logging out. |
| [`analytics`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#authentication-and-analytics) | The analytics providers and events to send. |

## Hooks

Functions you set on `window.sparkOptions`, which SparkLayer calls.

| Hook | When it runs |
| --- | --- |
| [`onReady`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onready) | When SparkLayer has initialised and the page's DOM has loaded. |
| [`onLoad`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onload) | Once while SparkLayer initialises, before `onReady`. |
| [`onLogout`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onlogout) | When the user logs out. |
| [`onCartLoad`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncartload) | When the cart is loaded. |
| [`onCartUpdate`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncartupdate) | Each time the cart is updated. |
| [`preCartUpdateListener`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#precartupdatelistener) | Just before SparkLayer's add to cart updates the cart, to change the update. |
| [`onCheckoutValidation`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncheckoutvalidation) | Each time the cart loads or changes, to block checkout. |

If a hook throws, SparkLayer shows a [hook error code](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#hook-error-codes).

## Methods

The methods on `window.spark`. Call them once SparkLayer is ready.

**Customers and session**

| Method | What it does | Returns |
| --- | --- | --- |
| [`isLoggedIn()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#isloggedin) | Checks whether the user is logged in. | `Promise<boolean>` |
| [`switchImpersonatingCustomer(customerId)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#switchimpersonatingcustomer) | Switches the customer a sales agent acts for, or ends it with `null`. | `Promise<UserData \| null>` |
| [`refreshGlobalData()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#refreshglobaldata) | Refetches the active customer and site configuration. | `Promise<UserData \| null>` |
| [`getActiveCustomerVerificationToken()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getactivecustomerverificationtoken) | Gets a fresh form customer verification token. | `Promise<string \| null>` |
| [`setActiveCompanySection(sectionId)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#setactivecompanysection) | Selects the company section to buy for, then reloads. | `Promise<boolean>` |

**Products and pricing**

| Method | What it does | Returns |
| --- | --- | --- |
| [`getProduct(parentProductId)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getproduct) | Fetches a product by its parent product ID. | `Promise<Product>` |
| [`getProductBySlug(slug)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getproductbyslug) | Fetches a product by its slug. | `Promise<Product>` |
| [`getVariant(parentProductId, variantSku)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getvariant) | Fetches a variant. | `Promise<ProductVariant>` |
| [`getPriceForProduct(parentProductId)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getpriceforproduct) | Gets a product's "from" price and how many prices it has. | `Promise<SimplifiedProductPrice>` |
| [`getPricingForVariant(parentProductId, variantSku)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getpricingforvariant) | Gets a variant's price, RRP and price breaks. | `Promise<{ price, rrp, … }>` |
| [`getRrpPriceForVariant(parentProductId, variantSku)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getrrppriceforvariant) | Gets a variant's RRP. | `Promise<{ rrp, currencyCode }>` |
| [`getPackSizeForVariant(parentProductId, variantSku)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getpacksizeforvariant) | Gets a variant's pack size. | `Promise<number>` |
| [`calculatePricingForVariant(parentProductId, variantSku, qty)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#calculatepricingforvariant) | Prices a quantity of a variant. | `Promise<ProductVariantPricing>` |
| [`calculatePricingForVariantData(variant, qty)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#calculatepricingforvariantdata) | Prices a quantity from variant data you have, without a request. | `ProductVariantPricing` |

**Cart**

| Method | What it does | Returns |
| --- | --- | --- |
| [`getCart()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getcart) | Fetches the cart. | `Promise<Cart \| null>` |
| [`getCartCache()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getcartcache) | Gets the cached cart, without a request. | `Cart \| null` |
| [`updateCart(input)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#updatecart) | Adds, updates or removes items and sets cart fields. | `Promise<CartResults[] \| null>` |
| [`addCustomLineItem(customItem)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#addcustomlineitem) | Adds a line not tied to a SKU. | `Promise<Cart \| null>` |
| [`externalClearBasket()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#externalclearbasket) | Clears the cart, for your order confirmation page. | `Promise<void>` |

**Drawer**

| Method | What it does | Returns |
| --- | --- | --- |
| [`openDrawer(initialTab)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#opendrawer) | Opens the drawer, on the Cart tab unless you pass another. | `void` |
| [`closeDrawer()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#closedrawer) | Closes the drawer. | `void` |

**Files and GraphQL**

| Method | What it does | Returns |
| --- | --- | --- |
| [`uploadFile(fileName, fileData)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#uploadfile) | Uploads a file to attach to a cart line. | `Promise<string>` |
| [`fetch(query, variables)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#fetch) | Runs a GraphQL query or mutation as the user. | `Promise<FetchResponse>` |

`window.spark.options` holds the [options](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#options) SparkLayer is running with.

## Events and components

| Name | What it is |
| --- | --- |
| [`spark-variant-change`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#spark-variant-change) | Event: the customer selects a variant in `spark-pdp` or `spark-product-card`. |
| [`spark-file-attachment-changed`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#spark-file-attachment-changed) | Event: the files in a `spark-file-upload-field` change. |
| [`spark-file-attachment-failed`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#spark-file-attachment-failed) | Event: a file fails to upload. |
| [`view-update`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#view-update) | Event you dispatch to switch an open drawer to a tab. |
| [`<spark-pdp>`, `<spark-product-card>`, `<spark-product-matrix>`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#web-components) | Components: the product detail, product card and product matrix interfaces. |
| [`<spark-product-price>`, `<spark-product-rrp>`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#web-components) | Components: the customer's price or the RRP for a product, anywhere on the page. |
| [`<spark-file-upload-field>`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#web-components) | Component: a file upload field for the product page. |
| [`<spark-drawer>`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#web-components) | Component: the drawer, which SparkLayer adds when needed. |

## TypeScript types

Download [spark.d.ts](https://docs.sparklayer.io/developers/javascript-sdk/spark.d.ts) for autocomplete and type checking in your editor, or point your AI assistant at it. It's generated from the [Types](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md) page.

```typescript title="cart.ts"
/// <reference path="./spark.d.ts" />

export async function countCartLines() {
  const cart = await window.spark.getCart(); // Cart | null
  return cart?.items.length ?? 0;
}
```

## Next steps

- [Set up the SDK](https://docs.sparklayer.io/developers/javascript-sdk/setup.md): How the SDK loads, how to add your options and hooks, and how to wait for it.
- [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md): Add, update and remove items with updateCart, and attach custom attributes and files.
- [Headless and React](https://docs.sparklayer.io/developers/javascript-sdk/headless.md): Initialise SparkLayer yourself and use it from React.


---

# Options

URL: https://docs.sparklayer.io/developers/javascript-sdk/reference/options

Every window.sparkOptions setting for the SparkLayer Core Script: site and platform, redirects, button selectors, display, translations, checkout and auth.

`window.sparkOptions` configures SparkLayer. It has the type `SparkLayerOptions`, and SparkLayer merges your options with its built-in defaults and the defaults for your `platform`, so you only set what you want to change. `siteId` is the only option you must provide: without it SparkLayer is disabled.

When you add options in your theme, extend the existing object (`window.sparkOptions = { ...window.sparkOptions, … }`) so you don't remove options set by the Core Script or other snippets. See [Set up the SDK](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#add-your-own-options-and-hooks).

```typescript
type SparkLayerOptions = {
  sparkDomain: "app.sparklayer.io" | "test.app.sparklayer.io";
  platform: "base" | "bigcommerce" | "shopify" | "wix" | "woocommerce" | "magento";
  siteId: string;
  rootUrl: string;
  accountRedirect: {
    urlRegex?: RegExp;
    goTo?: string;
  };
  cartRedirect: {
    urlRegex?: RegExp;
    goTo?: string;
  };
  wordpressSiteUrl?: string;
  accountButtonSelectors: string;
  logoutButtonSelectors: string;
  cartButtonSelectors: string;
  loginButtonSelectors: string;
  display: DisplayOptions;
  termsAndConditionsLink: string;
  language: string;
  locale: string | null;
  translations: Translations;
  showTranslations: boolean;
  checkoutCustomElements: CheckoutElementConfig[];
  paymentMethodsOrder: PaymentMethodName[];
  saveToAddressBookDefault: boolean;
  productLink: string;
  customAccountDetails: {
    title: string;
    value: string | number;
    displayText?: string;
    type?: CustomAccountDetailLinkType;
  }[];
  onCheckoutValidation(
    cart: Cart,
    cartUiState: CartUIState,
  ): Promise<{ message: string }[] | null>;
  onCartUpdate(cart: Cart, results: CartResults[]): Promise<void>;
  onCartLoad(cart: Cart): Promise<void>;
  preCartUpdateListener(input: Partial<UpdateCart>): Promise<Partial<UpdateCart>>;
  onReady?(spark: Spark): Promise<void>;
  onLoad?(spark: Spark): Promise<void>;
  onLogout?(): Promise<void>;
  shopify?: {
    useAppProxy?: boolean;
  };
  bigcommerce?: {
    appClientId?: string;
  };
  auth: {
    user?: string;
    token?: string;
  };
  authLogoutUri: string | null;
  analytics?: AnalyticsOptions;
  igniteCheckoutContext?: Record<string, unknown>;
};
```

The function-valued options (`onReady`, `onCartUpdate` and the rest) are on the [Hooks](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md) page.

## Site and platform

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `siteId` | `string` | – | Your site ID. Required. |
| `sparkDomain` | `"app.sparklayer.io" \| "test.app.sparklayer.io"` | `"app.sparklayer.io"` | The domain of the SparkLayer API. |
| `platform` | `"base" \| "bigcommerce" \| "shopify" \| "wix" \| "woocommerce" \| "magento"` | `"base"` | Sets the default options for your ecommerce platform. |
| `rootUrl` | `string` | `""` | The root URL used to prefix any URLs SparkLayer creates, generally used for i18n. A trailing `/` is removed. |
| `wordpressSiteUrl?` | `string` | – | The URL of the WordPress site when using the WooCommerce platform. |
| `shopify?` | `{ useAppProxy?: boolean }` | – | Shopify-specific options. |
| `shopify.useAppProxy?` | `boolean` | `true` on Shopify | Send API requests through the Shopify app proxy (`/tools/sparklayer` under `rootUrl`) instead of calling `sparkDomain` directly. |
| `bigcommerce?` | `{ appClientId?: string }` | – | BigCommerce-specific options. |
| `bigcommerce.appClientId?` | `string` | – | Your BigCommerce app client ID. |

## Links and redirects

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `accountRedirect` | `{ urlRegex?: RegExp; goTo?: string }` | – | When a logged-in user visits a path matching `urlRegex`, they're sent to `goTo` with the account drawer open. |
| `accountRedirect.urlRegex?` | `RegExp` | – | Pattern matched against the current path. |
| `accountRedirect.goTo?` | `string` | – | Path (relative to `rootUrl`) to redirect to. |
| `cartRedirect` | `{ urlRegex?: RegExp; goTo?: string }` | – | When a logged-in user visits a path matching `urlRegex`, they're sent to `goTo` with the cart drawer open. |
| `cartRedirect.urlRegex?` | `RegExp` | – | Pattern matched against the current path. |
| `cartRedirect.goTo?` | `string` | – | Path (relative to `rootUrl`) to redirect to. |
| `termsAndConditionsLink` | `string` | `/terms-of-service` (`/policies/terms-of-service` on Shopify) | Link to your terms and conditions. |
| `productLink` | `string` | `/:product-slug:` (`/products/:product-slug:` on Shopify, `/product-page/:product-slug:` on Wix) | The link to a product page, where `:product-slug:` is replaced with the product's slug. |

## Button selectors

SparkLayer attaches to elements matching these CSS selectors. The defaults below are for the `base` platform; BigCommerce, Magento, Shopify, Wix and WooCommerce set their own.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `accountButtonSelectors` | `string` | `[href*="/account"]:not([href$="/account/logout"]), [data-spark-link=account]` | Selectors for the account button. |
| `logoutButtonSelectors` | `string` | `[href$="/account/logout"], [data-spark-link=logout]` | Selectors for the logout button. |
| `cartButtonSelectors` | `string` | `[href$="/cart"], [data-spark-link=cart]` | Selectors for the cart button. |
| `loginButtonSelectors` | `string` | `[href$="/spark-b2b-login"], [data-spark-link=login]` | Selectors for the login button. |

If your site re-renders these buttons, they can lose SparkLayer's click handlers. Open the drawer from your own click handler instead, with [`openDrawer()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#opendrawer).

## Display, language and translations

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `display` | [`DisplayOptions`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#displayoptions) | See [`DisplayOptions`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#displayoptions) | Display options for SparkLayer. |
| `language` | `string` | `"en"` | The language SparkLayer uses. |
| `locale` | `string \| null` | The browser's locale | The locale used for formatting: currently only dates. Examples: `en-GB`, `en-US`, `de-DE`. An empty or unsupported value falls back to the browser locale with a console warning. |
| `translations` | [`Translations`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#translations) | – | Override internal translations, keyed by language code. |
| `showTranslations` | `boolean` | `false` | Shows translation keys instead of text, which helps you debug translations. |

## Checkout and account

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `checkoutCustomElements` | [`CheckoutElementConfig`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#checkoutelementconfig)`[]` | – | Elements to display in checkout: SparkLayer's standard fields (by `id`) or your own custom ones. |
| `paymentMethodsOrder` | [`PaymentMethodName`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#paymentmethodname)`[]` | – | The order in which payment methods are shown. |
| `saveToAddressBookDefault` | `boolean` | `true` | Whether new addresses are saved to the user's address book by default. |
| `customAccountDetails` | `{ title: string; value: string \| number; displayText?: string; type?: CustomAccountDetailLinkType }[]` | – | Title and value pairs to show on a customer's My Details panel. Set `type` (see [`CustomAccountDetailLinkType`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#customaccountdetaillinktype)) to format the value as a link. |
| `igniteCheckoutContext?` | `Record<string, unknown>` | – | A JSON object of checkout context data to pass to Ignite. |

To validate the cart before checkout, use the [`onCheckoutValidation`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncheckoutvalidation) hook.

## Authentication and analytics

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `auth` | `{ user?: string; token?: string }` | – | Credentials for SparkLayer auth. |
| `auth.user?` | `string` | – | The user to authenticate as. |
| `auth.token?` | `string` | – | The token for that user. |
| `authLogoutUri` | `string \| null` | `null` | The logout URI for SparkLayer auth. After logging out, SparkLayer redirects to this path under `rootUrl`. |
| `analytics?` | [`AnalyticsOptions`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#analyticsoptions) | – | Analytics providers and events. See [Event tracking for analytics](https://docs.sparklayer.io/developers/frontend/technical-information.md#event-tracking-for-analytics-google-analytics-ga4). |

## Next steps

- [Set up the SDK](https://docs.sparklayer.io/developers/javascript-sdk/setup.md): Where to set your options so they're in place before the Core Script loads.
- [Hooks](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md): The functions on sparkOptions that SparkLayer calls at key moments.
- [Headless and React](https://docs.sparklayer.io/developers/javascript-sdk/headless.md): Pass these options to window\.initSpark() on a headless storefront.


---

# Hooks

URL: https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks

The SparkLayer SDK hooks, from onReady and onCartUpdate to preCartUpdateListener and onCheckoutValidation: when each runs, what it receives and returns.

Hooks are functions you set on `window.sparkOptions`. SparkLayer calls them at key points so you can run your own code. Each hook returns a promise, so define them as `async` functions. The optional hooks (`onReady`, `onLoad`, `onLogout`) do nothing unless you set them; the others have defaults that do nothing (or, for `preCartUpdateListener`, return the input unchanged).

Set hooks before the Core Script loads. A hook with the same name replaces the earlier one, so keep a reference to any hook that's already set and call it from yours:

```html title="Theme <head>, before the SparkLayer script"
<script>
  (function () {
    var options = (window.sparkOptions = window.sparkOptions || {});
    var previous = options.onCartUpdate;

    options.onCartUpdate = async function (cart, results) {
      if (previous) await previous(cart, results);
      // Your code here
    };
  })();
</script>
```

The examples below use the same pattern. See [Add your own options and hooks](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#add-your-own-options-and-hooks).

| Hook | When it runs |
| --- | --- |
| [`onReady`](#onready) | When SparkLayer has initialised and the page's DOM has loaded. |
| [`onLoad`](#onload) | Once while SparkLayer initialises, before `onReady`. |
| [`onLogout`](#onlogout) | When the user logs out. |
| [`onCartLoad`](#oncartload) | When the cart is loaded. |
| [`onCartUpdate`](#oncartupdate) | Each time the cart is updated. |
| [`preCartUpdateListener`](#precartupdatelistener) | Just before the cart is updated, to change the update. |
| [`onCheckoutValidation`](#oncheckoutvalidation) | Each time the cart loads or changes, to block checkout. |

## onReady()

Called when SparkLayer is ready: after it has initialised and the page's DOM has loaded. It runs whether or not the user is logged in. Start most of your code here.

```typescript title="Signature"
onReady?(spark: Spark): Promise<void>;
```

| Name | Type | Description |
| --- | --- | --- |
| `spark` | [`Spark`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#spark) | The initialised Spark object. |

**Returns:** `Promise<void>`

```javascript title="sparkOptions"
const previousOnReady = window.sparkOptions?.onReady;
window.sparkOptions = {
  ...window.sparkOptions,
  onReady: async (spark) => {
    if (previousOnReady) await previousOnReady(spark);
    if (!(await spark.isLoggedIn())) return;
    // Safe to call spark methods here
  },
};
```

To wait for SparkLayer from a script that may run later, use [`window.sparkReady`](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#wait-for-sparklayer).

## onLoad()

Called once while SparkLayer initialises, after translations have loaded and before `onReady`. It runs whether or not the user is logged in.

```typescript title="Signature"
onLoad?(spark: Spark): Promise<void>;
```

| Name | Type | Description |
| --- | --- | --- |
| `spark` | [`Spark`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#spark) | The Spark object. |

**Returns:** `Promise<void>`

```javascript title="sparkOptions"
const previousOnLoad = window.sparkOptions?.onLoad;
window.sparkOptions = {
  ...window.sparkOptions,
  onLoad: async (spark) => {
    if (previousOnLoad) await previousOnLoad(spark);
    document.documentElement.dataset.sparkPlatform = spark.options.platform;
  },
};
```

## onLogout()

Called when the user logs out. On a headless storefront, use it to log the customer out of your own app too (see [Headless and React](https://docs.sparklayer.io/developers/javascript-sdk/headless.md#load-sparklayer-in-nextjs)).

```typescript title="Signature"
onLogout?(): Promise<void>;
```

**Returns:** `Promise<void>`

```javascript title="sparkOptions"
const previousOnLogout = window.sparkOptions?.onLogout;
window.sparkOptions = {
  ...window.sparkOptions,
  onLogout: async () => {
    if (previousOnLogout) await previousOnLogout();
    sessionStorage.removeItem('b2bCampaign');
  },
};
```

## onCartLoad()

Called when the cart is loaded. Use it to trigger analytics, for example.

```typescript title="Signature"
onCartLoad(cart: Cart): Promise<void>;
```

| Name | Type | Description |
| --- | --- | --- |
| `cart` | [`Cart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cart) | The loaded cart. |

**Returns:** `Promise<void>`

```javascript title="sparkOptions"
const previousOnCartLoad = window.sparkOptions?.onCartLoad;
window.sparkOptions = {
  ...window.sparkOptions,
  onCartLoad: async (cart) => {
    if (previousOnCartLoad) await previousOnCartLoad(cart);
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({ event: 'b2b_cart_load', lines: cart.items.length, currency: cart.currencyCode });
  },
};
```

## onCartUpdate()

Called when the cart is updated. Use it to trigger analytics or open the cart drawer, for example.

```typescript title="Signature"
onCartUpdate(cart: Cart, results: CartResults[]): Promise<void>;
```

| Name | Type | Description |
| --- | --- | --- |
| `cart` | [`Cart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cart) | The updated cart. |
| `results` | [`CartResults`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cartresults)`[]` | The result of each change in the update. |

**Returns:** `Promise<void>`

```javascript title="sparkOptions"
const previousOnCartUpdate = window.sparkOptions?.onCartUpdate;
window.sparkOptions = {
  ...window.sparkOptions,
  onCartUpdate: async (cart, results) => {
    if (previousOnCartUpdate) await previousOnCartUpdate(cart, results);
    window.spark.openDrawer('cart');
  },
};
```

For more, see [Open the cart drawer](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#open-the-cart-drawer) and [Send cart changes to your analytics](https://docs.sparklayer.io/developers/javascript-sdk/events-and-analytics.md#send-cart-changes-to-your-analytics).

## preCartUpdateListener()

Called just before one of SparkLayer's add-to-cart buttons updates the cart. Use it to change the products before the update is sent: for example, to add custom attributes.

```typescript title="Signature"
preCartUpdateListener(input: Partial<UpdateCart>): Promise<Partial<UpdateCart>>;
```

| Name | Type | Description |
| --- | --- | --- |
| `input` | `Partial<`[`UpdateCart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#updatecart)`>` | The cart update about to be sent. It has only the products being added, not the current cart. |

**Returns:** `Promise<Partial<UpdateCart>>`: the cart update to send, changed or not. SparkLayer sends whatever you return.

```javascript title="sparkOptions"
const previousPreCartUpdate = window.sparkOptions?.preCartUpdateListener;
window.sparkOptions = {
  ...window.sparkOptions,
  preCartUpdateListener: async (input) => {
    const update = previousPreCartUpdate ? await previousPreCartUpdate(input) : input;
    const length = document.querySelector('#shirt-length')?.value;
    if (!length || !update.products) return update;
    for (const product of update.products) {
      product.customAttributes = [...(product.customAttributes ?? []), { key: 'Shirt Length', value: length }];
    }
    return update;
  },
};
```

See [Add attributes to SparkLayer's add to cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#add-attributes-to-sparklayers-add-to-cart) for more examples, including files.

## onCheckoutValidation()

Checks whether the user can check out with their current cart. It runs each time the cart loads or changes, and receives the current checkout step, so your rules can vary by step. It must be asynchronous.

```typescript title="Signature"
onCheckoutValidation(
  cart: Cart,
  cartUiState: CartUIState,
): Promise<{ message: string }[] | null>;
```

| Name | Type | Description |
| --- | --- | --- |
| `cart` | [`Cart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cart) | The current cart. |
| `cartUiState` | [`CartUIState`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cartuistate) | The current checkout step. |

**Returns:** `Promise<{ message: string }[] | null>`: an array of error objects, or `null` if there are no errors. SparkLayer shows each `message` to the customer.

```javascript title="sparkOptions"
const previousOnCheckoutValidation = window.sparkOptions?.onCheckoutValidation;
window.sparkOptions = {
  ...window.sparkOptions,
  onCheckoutValidation: async (cart, cartUiState) => {
    const errors = (previousOnCheckoutValidation && (await previousOnCheckoutValidation(cart, cartUiState))) || [];
    const samples = cart.items
      .filter((item) => item.sku.startsWith('SAMPLE-'))
      .reduce((total, item) => total + item.quantity, 0);
    if (samples > 3) errors.push({ message: 'You can order up to 3 samples per order.' });
    return errors.length ? errors : null;
  },
};
```

See [Add custom checkout validation](https://docs.sparklayer.io/developers/javascript-sdk/checkout.md#add-custom-checkout-validation).

## Hook error codes

If `onReady`, `onCartLoad` or `onCartUpdate` throws an error when SparkLayer calls it, SparkLayer shows a system error toast with one of these codes and logs the error to the browser console. (SparkLayer doesn't wait for these hooks, so an `async` hook that rejects later shows no code: the browser logs it as an unhandled rejection.)

| Code | Hook that failed |
| --- | --- |
| `OPTIONS:HOOK:OR` | `onReady` |
| `OPTIONS:HOOK:OCL` | `onCartLoad` |
| `OPTIONS:HOOK:OCU` | `onCartUpdate` |

If customers report one of these codes, check that hook in your `sparkOptions` and fix the error shown in the console.

## Next steps

- [Events and analytics](https://docs.sparklayer.io/developers/javascript-sdk/events-and-analytics.md): Run your code from hooks and DOM events, and send B2B events to your analytics.
- [Checkout](https://docs.sparklayer.io/developers/javascript-sdk/checkout.md): Block checkout with onCheckoutValidation, including rules chained together.
- [Methods](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md): Every window\.spark method you can call from your hooks.


---

# Methods

URL: https://docs.sparklayer.io/developers/javascript-sdk/reference/methods

Every window.spark method in the SparkLayer SDK, such as getCart, updateCart, getPricingForVariant and fetch, with parameters, return values and examples.

## Wait for SparkLayer

`window.spark` is set as soon as the Core Script runs, but its methods only work once SparkLayer is ready. Call them from the `onReady` hook, or add the [Wait for SparkLayer](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#wait-for-sparklayer) snippet and start with `const spark = await window.sparkReady;`, as the examples on this page do.

## The Spark object

The `Spark` object is available as `window.spark`, and is passed to the [`onReady`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onready) and [`onLoad`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onload) hooks. Its public members are:

```typescript
type Spark = {
  options: SparkLayerOptions;
  isLoggedIn(): Promise<boolean>;
  switchImpersonatingCustomer(customerId: string | null): Promise<UserData | null>;
  refreshGlobalData(): Promise<UserData | null>;
  getActiveCustomerVerificationToken(): Promise<string | null>;
  setActiveCompanySection(sectionId: string): Promise<boolean>;
  getProduct(parentProductId: string): Promise<Product>;
  getProductBySlug(slug: string): Promise<Product>;
  getVariant(parentProductId: string, variantSku: string): Promise<ProductVariant>;
  getPriceForProduct(parentProductId: string): Promise<SimplifiedProductPrice>;
  getPricingForVariant(
    parentProductId: string,
    variantSku: string,
  ): Promise<{
    price: number | null;
    rrp: number | null;
    rrpCurrencyCode: string | null;
    priceBreaks: VariantPriceBreak[];
    currencyCode: string;
  }>;
  getRrpPriceForVariant(
    parentProductId: string,
    variantSku: string,
  ): Promise<{ rrp: number | null; currencyCode: string | null }>;
  getPackSizeForVariant(parentProductId: string, variantSku: string): Promise<number>;
  calculatePricingForVariant(
    parentProductId: string,
    variantSku: string,
    qty: number,
    qtyAcrossVariants?: number | null,
  ): Promise<ProductVariantPricing>;
  calculatePricingForVariantData(
    variant: ProductVariantDataPricing,
    qty: number,
    qtyAcrossVariants?: number | null,
  ): ProductVariantPricing;
  getCart(): Promise<Cart | null>;
  getCartCache(): Cart | null;
  updateCart(
    input: Partial<UpdateCart>,
    cartSuccessHandledLocally?: boolean,
    cartErrorsHandledLocally?: boolean,
  ): Promise<CartResults[] | null>;
  addCustomLineItem(customItem: CustomLineItemInput): Promise<Cart | null>;
  externalClearBasket(): Promise<void>;
  openDrawer(initialTab?: DrawerUIState): void;
  closeDrawer(): void;
  uploadFile(fileName: string, fileData: Blob): Promise<string>;
  fetch<Q extends GraphqlQueryOrMutation<unknown, Record<string, unknown>, GraphqlError | GraphqlExtensionError>>(
    query: Q,
    variables?: VariablesOf<Q>,
    useImpersonatingCustomer?: boolean,
    bypassAppProxy?: boolean,
    signal?: AbortSignal,
  ): Promise<FetchResponse<ResponseOf<Q>, ErrorOf<Q>>>;
};
```

### options

**Type:** [`SparkLayerOptions`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#sparklayeroptions)

The options SparkLayer is running with, after merging your `sparkOptions` with the platform defaults. See [Options](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md).

```javascript title="Any script"
const spark = await window.sparkReady;
console.log(spark.options.platform, spark.options.language);
```

## Customers and session

### isLoggedIn()

Checks whether the user is logged in.

```typescript title="Signature"
isLoggedIn(): Promise<boolean>;
```

**Returns:** `Promise<boolean>`

```javascript title="Any script"
const spark = await window.sparkReady;
if (await spark.isLoggedIn()) {
  // Show B2B content
}
```

### switchImpersonatingCustomer()

Switches the customer a sales agent is impersonating, or ends impersonation when you pass `null`.

```typescript title="Signature"
switchImpersonatingCustomer(customerId: string | null): Promise<UserData | null>;
```

| Name | Type | Description |
| --- | --- | --- |
| `customerId` | `string \| null` | The customer to impersonate, or `null` to end impersonation. |

**Returns:** `Promise<`[`UserData`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#userdata)` | null>`

```javascript title="Any script"
const spark = await window.sparkReady;
const customer = await spark.switchImpersonatingCustomer('<CUSTOMER_ID>');
await spark.switchImpersonatingCustomer(null); // End impersonation
```

### refreshGlobalData()

Refetches the current active customer and site configuration, and updates the cached copy both are read from.

```typescript title="Signature"
refreshGlobalData(): Promise<UserData | null>;
```

**Returns:** `Promise<`[`UserData`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#userdata)` | null>`

```javascript title="Any script"
const spark = await window.sparkReady;
const user = await spark.refreshGlobalData();
```

### getActiveCustomerVerificationToken()

Refetches the current active customer and returns a fresh form customer verification token. It uses the impersonated customer when a sales agent is impersonating, otherwise the logged-in customer.

```typescript title="Signature"
getActiveCustomerVerificationToken(): Promise<string | null>;
```

**Returns:** `Promise<string | null>`

```javascript title="Any script"
const spark = await window.sparkReady;
const token = await spark.getActiveCustomerVerificationToken();
```

### setActiveCompanySection()

Selects the company section used for purchasing. If the cart isn't empty, the user is asked to confirm and the cart is cleared. The page then reloads.

```typescript title="Signature"
setActiveCompanySection(sectionId: string): Promise<boolean>;
```

| Name | Type | Description |
| --- | --- | --- |
| `sectionId` | `string` | The ID of one of the logged-in customer's company sections. |

**Returns:** `Promise<boolean>`: `false` if the section isn't available to the customer, the user cancels, or the cart couldn't be cleared.

```javascript title="Any script"
const spark = await window.sparkReady;
const user = await spark.refreshGlobalData();
const section = user?.companySections[0];
if (section) await spark.setActiveCompanySection(section.id);
```

## Products and pricing

Each method takes your platform's parent product ID and, for a variant, its SKU. Prices are for the logged-in customer.

### getProduct()

Fetches the GraphQL product object for a parent product ID.

```typescript title="Signature"
getProduct(parentProductId: string): Promise<Product>;
```

| Name | Type | Description |
| --- | --- | --- |
| `parentProductId` | `string` | The parent product ID. |

**Returns:** `Promise<`[`Product`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#product)`>`

**Throws:** if the product isn't found or an error occurs fetching it.

```javascript title="Any script"
const spark = await window.sparkReady;
const product = await spark.getProduct('6660191387839');
console.log(product.variants.map((variant) => variant.sku));
```

### getProductBySlug()

Fetches the GraphQL product object for a product slug.

```typescript title="Signature"
getProductBySlug(slug: string): Promise<Product>;
```

| Name | Type | Description |
| --- | --- | --- |
| `slug` | `string` | The product slug. |

**Returns:** `Promise<`[`Product`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#product)`>`

**Throws:** if the product isn't found or an error occurs fetching it.

```javascript title="Any script"
const spark = await window.sparkReady;
const product = await spark.getProductBySlug('mother-mug');
```

### getVariant()

Fetches the GraphQL variant object for a parent product ID and variant SKU.

```typescript title="Signature"
getVariant(parentProductId: string, variantSku: string): Promise<ProductVariant>;
```

| Name | Type | Description |
| --- | --- | --- |
| `parentProductId` | `string` | The parent product ID. |
| `variantSku` | `string` | The variant SKU. |

**Returns:** `Promise<`[`ProductVariant`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#productvariant)`>`

**Throws:** if the product or variant isn't found or an error occurs fetching the product.

```javascript title="Any script"
const spark = await window.sparkReady;
const variant = await spark.getVariant('6660191387839', 'MUG-MOM');
console.log(variant.name, variant.stockDisplay?.status);
```

### getPriceForProduct()

Fetches the pricing for a parent product, including price breaks, the lowest price and the number of prices.

```typescript title="Signature"
getPriceForProduct(parentProductId: string): Promise<SimplifiedProductPrice>;
```

| Name | Type | Description |
| --- | --- | --- |
| `parentProductId` | `string` | The parent product ID. |

**Returns:** `Promise<`[`SimplifiedProductPrice`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#simplifiedproductprice)`>`: all price-related data for the parent product, including price breaks, the lowest price and the number of prices. Use the number of prices to decide whether to show "from" before the price.

**Throws:** if the product isn't found or an error occurs fetching it.

```javascript title="Any script"
const spark = await window.sparkReady;
const { fromPrice, numberOfPrices, currencyCode } = await spark.getPriceForProduct('6660191387839');
const label = `${numberOfPrices > 1 ? 'From ' : ''}${fromPrice} ${currencyCode}`;
```

### getPricingForVariant()

Fetches the pricing for a variant.

```typescript title="Signature"
getPricingForVariant(
  parentProductId: string,
  variantSku: string,
): Promise<{
  price: number | null;
  rrp: number | null;
  rrpCurrencyCode: string | null;
  priceBreaks: VariantPriceBreak[];
  currencyCode: string;
}>;
```

| Name | Type | Description |
| --- | --- | --- |
| `parentProductId` | `string` | The parent product ID. |
| `variantSku` | `string` | The variant SKU. |

**Returns:** all price-related data for the variant: `price`, `rrp`, `rrpCurrencyCode`, `priceBreaks` (each a [`VariantPriceBreak`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#variantpricebreak)) and `currencyCode`.

**Throws:** if the product or variant isn't found or an error occurs fetching the product.

```javascript title="Any script"
const spark = await window.sparkReady;
const pricing = await spark.getPricingForVariant('6660191387839', 'MUG-MOM');
console.log(pricing.price, pricing.currencyCode, pricing.priceBreaks);
```

### getRrpPriceForVariant()

Fetches the RRP for a variant.

```typescript title="Signature"
getRrpPriceForVariant(
  parentProductId: string,
  variantSku: string,
): Promise<{ rrp: number | null; currencyCode: string | null }>;
```

| Name | Type | Description |
| --- | --- | --- |
| `parentProductId` | `string` | The parent product ID. |
| `variantSku` | `string` | The variant SKU. |

**Returns:** the RRP (`null` if not set for the currency) and the currency code.

**Throws:** if the product or variant isn't found or an error occurs fetching the product.

```javascript title="Any script"
const spark = await window.sparkReady;
const { rrp, currencyCode } = await spark.getRrpPriceForVariant('6660191387839', 'MUG-MOM');
```

### getPackSizeForVariant()

Fetches the pack size for a variant.

```typescript title="Signature"
getPackSizeForVariant(parentProductId: string, variantSku: string): Promise<number>;
```

| Name | Type | Description |
| --- | --- | --- |
| `parentProductId` | `string` | The parent product ID. |
| `variantSku` | `string` | The variant SKU. |

**Returns:** `Promise<number>`: the variant's pack size, or `1` if none is set.

**Throws:** if the product or variant isn't found or an error occurs fetching the product.

```javascript title="Any script"
const spark = await window.sparkReady;
const packSize = await spark.getPackSizeForVariant('6660191387839', 'MUG-MOM');
const quantity = Math.ceil(10 / packSize) * packSize; // Round 10 up to whole packs
```

### calculatePricingForVariant()

Returns the price for a quantity of a variant, given its parent product ID and SKU.

```typescript title="Signature"
calculatePricingForVariant(
  parentProductId: string,
  variantSku: string,
  qty: number,
  qtyAcrossVariants?: number | null,
): Promise<ProductVariantPricing>;
```

| Name | Type | Description |
| --- | --- | --- |
| `parentProductId` | `string` | The parent product ID. |
| `variantSku` | `string` | The variant SKU. |
| `qty` | `number` | The quantity to calculate pricing for. |
| `qtyAcrossVariants?` | `number \| null` | For tiered pricing, the quantity across variants (if configured). Defaults to `null`. |

**Returns:** `Promise<`[`ProductVariantPricing`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#productvariantpricing)`>`: the total price (quantity × unit price), the unit price and the price breaks.

**Throws:** if the product or variant isn't found or an error occurs fetching the product.

```javascript title="Any script"
const spark = await window.sparkReady;
const pricing = await spark.calculatePricingForVariant('6660191387839', 'MUG-MOM', 2);
console.log(pricing.totalPrice, pricing.unitPrice, pricing.currencyCode);
```

### calculatePricingForVariantData()

Calculates the pricing for a variant from variant data you already have, without fetching.

```typescript title="Signature"
calculatePricingForVariantData(
  variant: ProductVariantDataPricing,
  qty: number,
  qtyAcrossVariants?: number | null,
): ProductVariantPricing;
```

| Name | Type | Description |
| --- | --- | --- |
| `variant` | [`ProductVariantDataPricing`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#productvariantdatapricing) | Variant data, including the RRP and price breaks. A `ProductVariant` or `CartItem` works. |
| `qty` | `number` | The quantity to calculate pricing for. |
| `qtyAcrossVariants?` | `number \| null` | For tiered pricing, the quantity across variants (if configured). Defaults to `null`. |

**Returns:** [`ProductVariantPricing`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#productvariantpricing): the total price (quantity × unit price), the unit price and the price breaks.

```javascript title="Any script"
const spark = await window.sparkReady;
const variant = await spark.getVariant('6660191387839', 'MUG-MOM');
const pricing = spark.calculatePricingForVariantData(variant, 24); // No request
```

See [Live price as the quantity changes](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md#live-price-as-the-quantity-changes) for a full example.

## Cart

See [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md) for worked examples.

### getCart()

Fetches the cart from GraphQL.

```typescript title="Signature"
getCart(): Promise<Cart | null>;
```

**Returns:** `Promise<`[`Cart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cart)` | null>`: the cart, or `null` if it couldn't be fetched (an error toast is shown).

```javascript title="Any script"
const spark = await window.sparkReady;
const cart = await spark.getCart();
console.log(cart?.items.length, cart?.totals.total.charge.gross.number);
```

### getCartCache()

Gets the cached cart, if available, without a request.

```typescript title="Signature"
getCartCache(): Cart | null;
```

**Returns:** [`Cart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cart)` | null`: the cached cart, or `null` if it isn't available.

```javascript title="Any script"
const spark = await window.sparkReady;
const cart = spark.getCartCache() ?? (await spark.getCart());
```

### updateCart()

Runs an update cart mutation, shows the appropriate toasts and returns the result. It makes every change to the cart: adding, updating and removing items, and setting cart-level fields.

```typescript title="Signature"
updateCart(
  input: Partial<UpdateCart>,
  cartSuccessHandledLocally?: boolean,
  cartErrorsHandledLocally?: boolean,
): Promise<CartResults[] | null>;
```

| Name | Type | Description |
| --- | --- | --- |
| `input` | `Partial<`[`UpdateCart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#updatecart)`>` | Follows the GraphQL `updateCart` mutation's variables. Each product is a [`CartItemInput`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cartiteminput). |
| `cartSuccessHandledLocally?` | `boolean` | Don't show success toasts, as you'll handle the result yourself (useful in the cart, where the update itself shows the change). Defaults to `false`. |
| `cartErrorsHandledLocally?` | `boolean` | Don't show toasts for the messages in the results, as you'll handle them yourself. Defaults to `false`. |

**Returns:** `Promise<`[`CartResults`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cartresults)`[] | null>`: the results, or `null` if the update failed. It doesn't throw: on failure it shows an error toast and logs the error to the console. See [What updateCart returns](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#what-updatecart-returns).

```javascript title="Any script"
const spark = await window.sparkReady;
const results = await spark.updateCart({
  products: [{ sku: 'RED-SHIRT-M', adjustQuantity: 1 }],
});
```

### addCustomLineItem()

Adds a custom line item (a free-text name, price and quantity not tied to a SKU) to the cart. The active customer must have custom cart items enabled, otherwise the request is rejected.

```typescript title="Signature"
addCustomLineItem(customItem: CustomLineItemInput): Promise<Cart | null>;
```

| Name | Type | Description |
| --- | --- | --- |
| `customItem` | [`CustomLineItemInput`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#customlineiteminput) | The name, unit price (as a decimal string) and quantity. |

**Returns:** `Promise<`[`Cart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cart)` | null>`: the refreshed cart, or `null` if the item couldn't be added.

```javascript title="Any script"
const spark = await window.sparkReady;
const cart = await spark.addCustomLineItem({ name: 'Artwork set-up', quotedPrice: '25.00', quantity: 1 });
```

### externalClearBasket()

Tells SparkLayer to clear the basket. Designed for your order confirmation (thank you) page.

```typescript title="Signature"
externalClearBasket(): Promise<void>;
```

**Returns:** `Promise<void>`

```javascript title="Order confirmation page"
const spark = await window.sparkReady;
await spark.externalClearBasket();
```

## Drawer

### openDrawer()

Opens the SparkLayer drawer, optionally on a specific tab.

```typescript title="Signature"
openDrawer(initialTab?: DrawerUIState): void;
```

| Name | Type | Description |
| --- | --- | --- |
| `initialTab?` | [`DrawerUIState`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#draweruistate) | The tab to open on. Defaults to `"cart"`. |

**Returns:** `void`

```javascript title="Any script"
const spark = await window.sparkReady;
spark.openDrawer('account');
```

To switch a drawer that's already open to another tab, dispatch the [`view-update`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#view-update) event.

### closeDrawer()

Closes the SparkLayer drawer.

```typescript title="Signature"
closeDrawer(): void;
```

**Returns:** `void`

```javascript title="Any script"
const spark = await window.sparkReady;
spark.closeDrawer();
```

## Files and GraphQL

### uploadFile()

Uploads a file to the SparkLayer file store. Pass the returned ID as a cart item attribute to attach the file (see [Attach a file](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#attach-a-file)).

```typescript title="Signature"
uploadFile(fileName: string, fileData: Blob): Promise<string>;
```

| Name | Type | Description |
| --- | --- | --- |
| `fileName` | `string` | The name of the file, including its extension. It must match the type of the data in `fileData`. |
| `fileData` | `Blob` | The file data as a `Blob`. |

**Returns:** `Promise<string>`: the uploaded file's ID (a GID).

**Throws:** if the file type isn't supported, the file is too large, the file path is invalid, or the upload fails.

```javascript title="Any script"
const spark = await window.sparkReady;
const gid = await spark.uploadFile('design.png', fileBlob);
await spark.updateCart({
  products: [{ sku: 'SHIRT-CUSTOM', adjustQuantity: 1, customAttributes: [{ key: 'Design', value: JSON.stringify([gid]) }] }],
});
```

### fetch()

Runs a GraphQL query or mutation as the authenticated user.

```typescript title="Signature"
fetch<Q>(
  query: Q,
  variables?: VariablesOf<Q>,
  useImpersonatingCustomer?: boolean,
  bypassAppProxy?: boolean,
  signal?: AbortSignal,
): Promise<FetchResponse<ResponseOf<Q>, ErrorOf<Q>>>;
```

**Type parameter:** `Q extends GraphqlQueryOrMutation<unknown, Record<string, unknown>, GraphqlError | GraphqlExtensionError>`. See [`GraphqlQueryOrMutation`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#graphqlqueryormutation).

| Name | Type | Description |
| --- | --- | --- |
| `query` | `Q` | The GraphQL query string. |
| `variables?` | [`VariablesOf<Q>`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#variablesof) | The GraphQL variables. |
| `useImpersonatingCustomer?` | `boolean` | Whether to make the request as the customer being impersonated, rather than as the sales agent. |
| `bypassAppProxy?` | `boolean` | Call the API directly rather than through the platform's app proxy. |
| `signal?` | `AbortSignal` | Aborts the request, for example when its result is no longer needed. |

**Returns:** `Promise<`[`FetchResponse`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#fetchresponse)`<ResponseOf<Q>, ErrorOf<Q>>>`: a standard `Response` object. Check `status`, and call `json()` to get the `data` and `errors`.

```javascript title="Any script"
const spark = await window.sparkReady;
const response = await spark.fetch(`query { loggedInCustomer { id email } }`);
if (response.status === 200) {
  const { data, errors } = await response.json();
  if (!errors?.length) console.log(data.loggedInCustomer.email);
}
```

See [Run a GraphQL query](https://docs.sparklayer.io/developers/javascript-sdk/customers-and-accounts.md#run-a-graphql-query).

## Next steps

- [Types](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md): Cart, Product, UpdateCart and every other type these methods take and return.
- [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md): Add, update and remove items with updateCart, and attach custom attributes and files.
- [Products and pricing](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md): Show trade prices and live quantity pricing in your theme.


---

# Types

URL: https://docs.sparklayer.io/developers/javascript-sdk/reference/types

Every TypeScript type in the SparkLayer JavaScript SDK, from Cart, Product and UpdateCart to SparkLayerOptions and Spark, and where each one is used.

The objects you pass to the SDK and get back from it, written in TypeScript and listed A to Z. In JavaScript, they describe the shape of those objects. Every block on this page goes into [spark.d.ts](https://docs.sparklayer.io/developers/javascript-sdk/spark.d.ts), which you can download for autocomplete and type checking in your editor.

The cart, product and pricing types come from SparkLayer's GraphQL API. Their field types and nullability are inferred from how the SDK uses them, so treat a field as possibly `null` unless you're sure it's set.

## AccountSectionId

The sections of the My Account panel, used in [`display.sectionConfiguration`](#displayoptions) to reorder or hide them.

```typescript
type AccountSectionId =
  | "spark-slot-my-account"
  | "recent-activity"
  | "shopping-lists"
  | "favourites"
  | "financials"
  | "my-details"
  | "reports"
  | "address-book"
  | "company-users";
```

**Used by:** [`DisplayOptions`](#displayoptions)

## AnalyticsEventName

The B2B events SparkLayer can send to your analytics. See [Event tracking for analytics](https://docs.sparklayer.io/developers/frontend/technical-information.md#event-tracking-for-analytics-google-analytics-ga4) for what each event means.

```typescript
type AnalyticsEventName =
  | "addToCart"
  | "cartUpdate"
  | "shoppingListSave"
  | "shoppingListLoad"
  | "shoppingListDelete"
  | "csvUpload"
  | "quickAdd"
  | "finalStageCheckout"
  | "shippingUpdate"
  | "beginCheckout"
  | "purchase"
  | "viewCart";
```

**Used by:** [`AnalyticsOptions`](#analyticsoptions)

## AnalyticsOptions

The type of the `analytics` option: the providers to send events to, and which events each one gets. See [Event tracking for analytics](https://docs.sparklayer.io/developers/frontend/technical-information.md#event-tracking-for-analytics-google-analytics-ga4).

```typescript
type AnalyticsOptions = {
  providers: {
    // "ga" for Google Analytics (GA4), "gtm" for Google Tag Manager, or your own function
    handler: "ga" | "gtm" | ((eventName: AnalyticsEventName, eventParams: unknown) => void);
    // The events to send to this provider
    events: Partial<Record<AnalyticsEventName, boolean>>;
  }[];
};
```

**Used by:** the [`analytics`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#authentication-and-analytics) option

## Cart

The B2B cart.

```typescript
type Cart = {
  cartUuid: string;
  intent: string; // For example "ORDER"
  canCreateOrder: boolean;
  canCreateQuote: boolean;
  hasLaunched: boolean;
  lockedByUserId: string | null;
  lockedByUserLastAccessedAt: string | null;
  loadedFromPurchaseAt: string | null;
  loadedFromPurchaseType: string | null;
  items: CartItem[];
  validationErrors: CartValidationError[];
  taxInclusiveDisplay: boolean;
  totals: CartTotals;
  currencyCode: string;
  totalWeight: number | null;
  customerAddresses: { id: string; description: string }[];
  deliveryAddressId: string | null;
  customerReference: string | null;
  poNumber: string | null;
  shippingRequestedDate: string | null;
  customFields: { name: string; value: string }[];
  approvingFor: { name: string } | null;
  discounts: {
    id: string;
    slug: string;
    name: string;
    appliedCouponCodes: string[];
    amount: { net: number; gross: number; currencyCode: string };
  }[];
  discountsAreAvailable: boolean;
  couponCodes: string[];
  removedCouponCodes: string[];
  quote: {
    statusSlug: string;
    statusUpdated: string;
    expiry: string | null;
    assignedAgent: { id: string } | null;
    message: string | null;
    note: string | null;
  } | null;
};
```

**Used by:** [`getCart()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getcart), [`getCartCache()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getcartcache), [`addCustomLineItem()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#addcustomlineitem), [`onCartLoad`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncartload), [`onCartUpdate`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncartupdate), [`onCheckoutValidation`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncheckoutvalidation)

## CartItem

One line in the cart. It has every [`ProductVariant`](#productvariant) field (`sku`, `name`, `price` and so on) plus these:

```typescript
type CartItem = ProductVariant & {
  type: string;
  itemKey: string; // Identifies the line in updateCart
  quantity: number;
  customAttributes: { key: string; value: string; type?: string | null }[];
  lineTotal: CartLineAmount;
  lineTotalPreDiscounts: CartLineAmount;
  lineTotalDiscountAmount: CartLineAmount;
  unitTotal: CartLineAmount;
  unitTotalPreDiscounts: CartLineAmount;
  unitTotalDiscountAmount: CartLineAmount;
  quotedPrice: string | null;
  preorderQuantityDisplay: number | null;
};
```

**Used by:** [`Cart`](#cart) (`items`), [`calculatePricingForVariantData()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#calculatepricingforvariantdata)

## CartItemInput

One product in an [`UpdateCart`](#updatecart). Identify the line by `sku` or `itemKey`, and set the quantity with `adjustQuantity` (added to the current quantity; negative to remove) or `quantity` (the exact quantity; `0` removes the line).

```typescript
type CartItemInput = {
  sku?: string;
  itemKey?: string; // From a CartItem
  adjustQuantity?: number;
  quantity?: number;
  customAttributes?: { key: string; value: string; type?: string }[];
};
```

For a file, `value` is a JSON string of an array of file GIDs from [`uploadFile()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#uploadfile).

**Used by:** [`UpdateCart`](#updatecart) (`products`)

## CartLineAmount

An amount on a cart line, such as its total or unit price.

```typescript
type CartLineAmount = {
  net: number;
  gross: number;
  currencyCode: string;
  taxInclusiveDisplay: boolean;
};
```

**Used by:** [`CartItem`](#cartitem)

## CartMoney

An amount in the cart's totals.

```typescript
type CartMoney = { number: string };
```

**Used by:** [`CartTotals`](#carttotals)

## CartResults

The result for one product line in an `updateCart` call. See [What updateCart returns](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#what-updatecart-returns) for the `messages` types.

```typescript
type CartResults = {
  messages: { type: string }[];
  requestedQuantity: number;
  resultantQuantity: number;
  itemKey: string;
  sku: string;
  name: string;
};
```

**Used by:** [`updateCart()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#updatecart), [`onCartUpdate`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncartupdate)

## CartTotals

The cart's totals. Each amount is a [`CartMoney`](#cartmoney) object with a `number`.

```typescript
type CartTotals = {
  subTotal: {
    preDiscount: { net: CartMoney; gross: CartMoney };
    discount: { net: CartMoney; gross: CartMoney };
    charge: { net: CartMoney; gross: CartMoney };
  };
  shipping: {
    preDiscount: { net: CartMoney };
    discount: { net: CartMoney };
    charge: { net: CartMoney };
  };
  total: {
    charge: { gross: CartMoney; tax: CartMoney };
    discount: { net: CartMoney };
    preDiscount: { gross: CartMoney };
  };
};
```

**Used by:** [`Cart`](#cart) (`totals`)

## CartUIState

The current checkout step.

```typescript
type CartUIState = "cart" | "shipping" | "quote-details" | "payment" | "thanks";
```

**Used by:** [`onCheckoutValidation`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncheckoutvalidation)

## CartValidationError

A reason the cart can't be checked out yet, such as an order minimum that hasn't been met. Each error has a `type` code (for example `quantity-unavailable` or `pricing-unavailable`) and the fields for its kind.

The `type` is one of the cart validation codes the API uses: `maximum-order-item-quantity`, `maximum-order-totals`, `maximum-parent-quantity`, `maximum-variant-quantity`, `minimum-order-item-quantity`, `minimum-order-totals`, `minimum-parent-quantity`, `minimum-variant-quantity`, `pack-size`, `pricing-unavailable`, `pricing-unavailable-for-selected-qty` or `quantity-unavailable`.

```typescript
type CartValidationError = {
  type: string;
  amount?: number;
  amountGross?: number;
  minimum?: number;
  maximum?: number;
  productName?: string;
  parentSKU?: string;
  variantSKU?: string;
  packSize?: number;
  availableQuantity?: number;
  overridden?: boolean;
};
```

| Kind of error (GraphQL type) | Fields |
| --- | --- |
| `CartValidationErrorMinimumOrderTotals`, `CartValidationErrorMaximumOrderTotals` | `amount`, `amountGross` |
| `CartValidationErrorMinimumOrderItemQuantity` | `minimum` |
| `CartValidationErrorMaximumOrderItemQuantity` | `maximum` |
| `CartValidationErrorMinimumParentQuantity`, `CartValidationErrorMaximumParentQuantity` | `minimum` or `maximum`, `productName`, `parentSKU`, `overridden` |
| `CartValidationErrorMinimumVariantQuantity`, `CartValidationErrorMaximumVariantQuantity` | `minimum` or `maximum`, `variantSKU`, `overridden` |
| `CartValidationErrorPackSize` | `packSize`, `variantSKU`, `overridden` |
| `CartValidationErrorQuantityUnavailable` | `variantSKU`, `availableQuantity` |
| `CartValidationErrorPricingUnavailable`, `CartValidationErrorPricingUnavailableForSelectedQty` | `variantSKU` |

**Used by:** [`Cart`](#cart) (`validationErrors`)

## CheckoutElementConfig

One entry in `checkoutCustomElements`: a standard field by `id`, or a custom field by `name`. See [Custom field settings](https://docs.sparklayer.io/help/ordering/checkout-fields.md#custom-field-settings) for every key and [Standard checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md#turn-on-standard-checkout-fields) for the IDs.

```typescript
type CheckoutElementConfig = {
  // A standard field
  id?: "customer-reference" | "po-number" | "shipping-requested-date";
  // A custom field (required unless id is set)
  name?: string;
  // Customer-facing text, keyed by language code
  translations?: Record<string, { title: string; detail?: string; [messageKey: string]: string | undefined }>;
  // HTML attributes such as type, required, min, max, maxlength and pattern
  attributes?: Record<string, string | number | boolean>;
  // For select fields: the drop-down options, optionally in groups
  options?: {
    translations?: Record<string, { groupName: string }>;
    items: { value: string; translations: Record<string, { label: string }> }[];
  }[];
  // Returns a message key from translations if the value is invalid
  onChange?(value: string, element: HTMLElement): string | null | undefined;
};
```

**Used by:** the [`checkoutCustomElements`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#checkout-and-account) option

## CustomAccountDetailLinkType

Formats a `customAccountDetails` value as a link of this kind.

```typescript
type CustomAccountDetailLinkType = "email" | "phone" | "sms" | "website";
```

**Used by:** the [`customAccountDetails`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#checkout-and-account) option

## CustomLineItemInput

A custom line item: a free-text name, price and quantity not tied to a SKU.

```typescript
type CustomLineItemInput = {
  // The name shown on the custom line item
  name: string;
  // The price of a single unit, as a decimal string
  quotedPrice: string;
  quantity: number;
};
```

**Used by:** [`addCustomLineItem()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#addcustomlineitem)

## DisplayOptions

The type of the `display` option.

```typescript
type DisplayOptions = {
  orderListShowShippingAddress: boolean;
  customerReferenceHidden: boolean; // deprecated
  customerReferenceRequired: boolean; // deprecated
  customerReferenceMaxLength?: number; // deprecated
  darkTheme: boolean;
  savingsUseRrp: boolean;
  roundPriceBreakPercentages: boolean;
  showPriceBreakSavings: boolean;
  sectionConfiguration: {
    "my-account"?: {
      order?: AccountSectionId[];
      hide?: AccountSectionId[];
    };
  };
  showSlots: string[];
  showRrpToggle: boolean;
  showFavouritesLists: boolean;
  showShoppingLists: boolean;
  showSkus: boolean;
  hideFinancials?: boolean;
};
```

| Property | Default | What it does |
| --- | --- | --- |
| `sectionConfiguration` | `{}` | Reorder (`order`) or hide (`hide`) My Account sections by [`AccountSectionId`](#accountsectionid). See [My account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md). |
| `showSlots` | `[]` | Custom slots to show. See [Custom slots](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md). |
| `showFavouritesLists` | `true` | Whether to show the favourites lists feature. |
| `showShoppingLists` | `true` | Whether to show the shopping lists feature. |
| `showSkus` | `true` | Whether to show product SKUs on cart line items. |
| `darkTheme` | `false` | Use the dark theme. See [Customising design](https://docs.sparklayer.io/help/storefront/customising-design.md). |
| `savingsUseRrp` | `false` | Calculate savings against the RRP. |
| `roundPriceBreakPercentages` | `true` | Round price break percentages. |
| `showPriceBreakSavings` | `true` | Show savings on price breaks. |
| `showRrpToggle` | `false` | Show the RRP toggle. |
| `orderListShowShippingAddress` | `false` | Show the shipping address in the purchases list. |
| `hideFinancials?` | – | Hide the Financials section of My Account. |
| `customerReferenceHidden`, `customerReferenceRequired`, `customerReferenceMaxLength?` | `false`, `false`, – | Deprecated. Use a `{ id: 'customer-reference' }` entry in `checkoutCustomElements` instead. |

**Used by:** the [`display`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#display-language-and-translations) option

## DrawerUIState

A tab of the SparkLayer drawer.

```typescript
type DrawerUIState = "dashboard" | "browse-catalog" | "cart" | "sales-agent" | "account";
```

**Used by:** [`openDrawer()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#opendrawer), the [`view-update`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#view-update) event

## ErrorOf

The error type of a GraphQL query or mutation passed to `fetch`. For a plain query string, it's [`GraphqlError`](#graphqlerror).

```typescript
type ErrorOf<Q> = Q extends { readonly __graphqlTypes?: { error: infer TError } }
  ? TError
  : GraphqlError;
```

**Used by:** [`fetch()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#fetch)

## FetchResponse

The response returned by `fetch`: a standard `Response` whose `json()` resolves to the GraphQL response.

```typescript
interface FetchResponse<TData = unknown, TError = GraphqlError> extends Response {
  json(): Promise<{ data: TData; errors: TError[] }>;
}
```

**Used by:** [`fetch()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#fetch)

## GraphqlError

An entry in the `errors` array of a GraphQL response.

```typescript
type GraphqlError = {
  message: string;
  path?: (string | number)[];
  extensions?: { code?: string; [key: string]: unknown };
};
```

**Used by:** [`FetchResponse`](#fetchresponse), [`fetch()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#fetch)

## GraphqlExtensionError

A [`GraphqlError`](#graphqlerror) with a `code` in `extensions` that identifies the error.

```typescript
type GraphqlExtensionError = GraphqlError & {
  extensions: { code: string; [key: string]: unknown };
};
```

**Used by:** [`fetch()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#fetch)

## GraphqlQueryOrMutation

The query you pass to `fetch`. In JavaScript, pass it as a string, and the variables as a plain object. In TypeScript, a typed query can also carry its response, variables and error types, which [`ResponseOf`](#responseof), [`VariablesOf`](#variablesof) and [`ErrorOf`](#errorof) read back.

```typescript
type GraphqlQueryOrMutation<
  TResponse = unknown,
  TVariables = Record<string, unknown>,
  TError = GraphqlError,
> = string & {
  // Type-only: never set at runtime
  readonly __graphqlTypes?: { response: TResponse; variables: TVariables; error: TError };
};
```

**Used by:** [`fetch()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#fetch)

## PaymentMethodName

The payment methods you can list in `paymentMethodsOrder`.

```typescript
type PaymentMethodName = "paymentOnAccount" | "paymentByInvoice" | "upfrontPayment" | "quote";
```

**Used by:** the [`paymentMethodsOrder`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#checkout-and-account) option

## Product

A product, with its variants.

```typescript
type Product = {
  id: string;
  externalId: string; // Your platform's product ID
  slug: string;
  variants: ProductVariant[];
};
```

**Used by:** [`getProduct()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getproduct), [`getProductBySlug()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getproductbyslug), the [`spark-variant-change`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#spark-variant-change) event

## ProductVariant

One variant of a product, and the base of each [`CartItem`](#cartitem).

```typescript
type ProductVariant = {
  id: string;
  externalId: string; // Your platform's variant ID
  parentExternalId: string; // Your platform's product ID
  stockDisplay: {
    status: string; // For example "out_of_stock" or "backorder"
    units: number | null;
    available: unknown;
  } | null;
  restockDate: string | null;
  cartImageUrl: string | null;
  position: number;
  sku: string;
  barcode: string | null;
  slug: string;
  name: string;
  price: VariantPrice | null;
  rrp: unknown; // Legacy: use rrpV2
  rrpV2: { number: string; currency: string } | null;
  priceBreaks: VariantPriceBreak[];
  // Product settings, such as packSize, minOrderQuantity and maxOrderQuantity
  settings: { key: string; value: unknown }[];
  // The variant's options, such as { group: "Size", value: "M" }
  options: { group: string; value: string }[];
};
```

**Used by:** [`getVariant()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getvariant), [`Product`](#product) (`variants`), [`CartItem`](#cartitem), [`calculatePricingForVariantData()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#calculatepricingforvariantdata), the [`spark-variant-change`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#spark-variant-change) event

## ProductVariantDataPricing

The variant data `calculatePricingForVariantData` needs. A [`ProductVariant`](#productvariant) or [`CartItem`](#cartitem) has these fields.

```typescript
type ProductVariantDataPricing = {
  priceBreaks: VariantPriceBreak[] | null;
  rrpV2?: { number: string; currency: string } | null;
  unitTotal?: { currencyCode: string } | null; // Cart items only
};
```

**Used by:** [`calculatePricingForVariantData()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#calculatepricingforvariantdata)

## ProductVariantPricing

The price for a quantity of a variant: the total, the unit price at that quantity and the price breaks.

```typescript
type ProductVariantPricing = {
  totalPrice: number | null; // unitPrice × quantity
  totalRrpPrice: number | null;
  hasPriceBreaks: boolean;
  unitPrice: number | null; // The unit price at this quantity
  basePrice: number | null; // The unit price before price breaks
  priceBreaks: VariantPriceBreak[];
  priceBreakSavingsPercentage: number | null;
  rrpV2: { number: string; currency: string } | null;
  currencyCode: string;
  unitPriceBreakdown: {
    items: {
      unitOfMeasure: string | null;
      price: number;
      quantity: number;
      uomQuantity: number;
    }[];
  };
};
```

**Used by:** [`calculatePricingForVariant()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#calculatepricingforvariant), [`calculatePricingForVariantData()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#calculatepricingforvariantdata)

## ResponseOf

The `data` type of a GraphQL query or mutation passed to `fetch`. For a plain query string, it's `unknown`.

```typescript
type ResponseOf<Q> = Q extends { readonly __graphqlTypes?: { response: infer TResponse } }
  ? TResponse
  : unknown;
```

**Used by:** [`fetch()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#fetch)

## SimplifiedProductPrice

The "from" price across a product's variants, and how many different prices there are.

```typescript
type SimplifiedProductPrice = {
  numberOfPrices: number;
  numberOfPricesExcludingBreaks: number;
  numberOfRrpPrices: number;
  fromPrice: number | null;
  fromPriceExcludingBreaks: number | null;
  currencyCode: string;
  hasPriceBreaks: boolean;
  rrpPrice: number | null;
  rrpCurrencyCode: string | null;
  taxInclusiveDisplay: boolean;
};
```

If `numberOfPrices` is more than 1, show "from" before `fromPrice`.

**Used by:** [`getPriceForProduct()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getpriceforproduct)

## Spark

The `window.spark` object. See [Methods](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md) for each one.

```typescript
type Spark = {
  options: SparkLayerOptions;
  isLoggedIn(): Promise<boolean>;
  switchImpersonatingCustomer(customerId: string | null): Promise<UserData | null>;
  refreshGlobalData(): Promise<UserData | null>;
  getActiveCustomerVerificationToken(): Promise<string | null>;
  setActiveCompanySection(sectionId: string): Promise<boolean>;
  getProduct(parentProductId: string): Promise<Product>;
  getProductBySlug(slug: string): Promise<Product>;
  getVariant(parentProductId: string, variantSku: string): Promise<ProductVariant>;
  getPriceForProduct(parentProductId: string): Promise<SimplifiedProductPrice>;
  getPricingForVariant(
    parentProductId: string,
    variantSku: string,
  ): Promise<{
    price: number | null;
    rrp: number | null;
    rrpCurrencyCode: string | null;
    priceBreaks: VariantPriceBreak[];
    currencyCode: string;
  }>;
  getRrpPriceForVariant(
    parentProductId: string,
    variantSku: string,
  ): Promise<{ rrp: number | null; currencyCode: string | null }>;
  getPackSizeForVariant(parentProductId: string, variantSku: string): Promise<number>;
  calculatePricingForVariant(
    parentProductId: string,
    variantSku: string,
    qty: number,
    qtyAcrossVariants?: number | null,
  ): Promise<ProductVariantPricing>;
  calculatePricingForVariantData(
    variant: ProductVariantDataPricing,
    qty: number,
    qtyAcrossVariants?: number | null,
  ): ProductVariantPricing;
  getCart(): Promise<Cart | null>;
  getCartCache(): Cart | null;
  updateCart(
    input: Partial<UpdateCart>,
    cartSuccessHandledLocally?: boolean,
    cartErrorsHandledLocally?: boolean,
  ): Promise<CartResults[] | null>;
  addCustomLineItem(customItem: CustomLineItemInput): Promise<Cart | null>;
  externalClearBasket(): Promise<void>;
  openDrawer(initialTab?: DrawerUIState): void;
  closeDrawer(): void;
  uploadFile(fileName: string, fileData: Blob): Promise<string>;
  fetch<Q extends GraphqlQueryOrMutation<unknown, Record<string, unknown>, GraphqlError | GraphqlExtensionError>>(
    query: Q,
    variables?: VariablesOf<Q>,
    useImpersonatingCustomer?: boolean,
    bypassAppProxy?: boolean,
    signal?: AbortSignal,
  ): Promise<FetchResponse<ResponseOf<Q>, ErrorOf<Q>>>;
};
```

**Used by:** `window.spark`, [`window.initSpark()`](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#manual-initialisation-headless-only), [`onReady`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onready), [`onLoad`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onload)

## SparkLayerOptions

The type of `window.sparkOptions` and the options you pass to `window.initSpark()`. See [Options](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md) and [Hooks](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md) for each one.

```typescript
type SparkLayerOptions = {
  sparkDomain: "app.sparklayer.io" | "test.app.sparklayer.io";
  platform: "base" | "bigcommerce" | "shopify" | "wix" | "woocommerce" | "magento";
  siteId: string;
  rootUrl: string;
  accountRedirect: {
    urlRegex?: RegExp;
    goTo?: string;
  };
  cartRedirect: {
    urlRegex?: RegExp;
    goTo?: string;
  };
  wordpressSiteUrl?: string;
  accountButtonSelectors: string;
  logoutButtonSelectors: string;
  cartButtonSelectors: string;
  loginButtonSelectors: string;
  display: DisplayOptions;
  termsAndConditionsLink: string;
  language: string;
  locale: string | null;
  translations: Translations;
  showTranslations: boolean;
  checkoutCustomElements: CheckoutElementConfig[];
  paymentMethodsOrder: PaymentMethodName[];
  saveToAddressBookDefault: boolean;
  productLink: string;
  customAccountDetails: {
    title: string;
    value: string | number;
    displayText?: string;
    type?: CustomAccountDetailLinkType;
  }[];
  onCheckoutValidation(
    cart: Cart,
    cartUiState: CartUIState,
  ): Promise<{ message: string }[] | null>;
  onCartUpdate(cart: Cart, results: CartResults[]): Promise<void>;
  onCartLoad(cart: Cart): Promise<void>;
  preCartUpdateListener(input: Partial<UpdateCart>): Promise<Partial<UpdateCart>>;
  onReady?(spark: Spark): Promise<void>;
  onLoad?(spark: Spark): Promise<void>;
  onLogout?(): Promise<void>;
  shopify?: {
    useAppProxy?: boolean;
  };
  bigcommerce?: {
    appClientId?: string;
  };
  auth: {
    user?: string;
    token?: string;
  };
  authLogoutUri: string | null;
  analytics?: AnalyticsOptions;
  igniteCheckoutContext?: Record<string, unknown>;
};
```

**Used by:** `window.sparkOptions`, [`window.initSpark()`](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#manual-initialisation-headless-only), [`Spark`](#spark) (`options`)

## Translations

The type of the `translations` option: text overrides keyed by language code, then by translation key. See [Change text in the Core Script](https://docs.sparklayer.io/help/storefront/languages-and-international.md#change-text-in-the-core-script).

```typescript
type Translations = Record<string, Record<string, string>>;
```

**Used by:** the [`translations`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#display-language-and-translations) option

## UpdateCart

A change to the cart. Every field is optional: send only what you want to change. See [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md).

```typescript
type UpdateCart = {
  clearCart?: boolean;
  products?: CartItemInput[];
  deliveryAddressId?: string;
  customerReference?: string;
  poNumber?: string;
  shippingRequestedDate?: string;
  customFields?: { name: string; value: string }[];
  cartIntent?: string;
};
```

SparkLayer adds the impersonated customer and company section for you.

**Used by:** [`updateCart()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#updatecart), [`preCartUpdateListener`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#precartupdatelistener)

## UserData

The active customer. This lists the fields most integrations need; the object has more.

```typescript
type UserData = {
  id: string;
  email: string;
  name: string;
  companyName: string | null;
  customerVerificationToken: string | null;
  salesAgent: boolean;
  parentAccount: { id: string; name: string; email: string } | null;
  companySections: { id: string; name: string }[];
};
```

**Used by:** [`switchImpersonatingCustomer()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#switchimpersonatingcustomer), [`refreshGlobalData()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#refreshglobaldata)

## VariablesOf

The variables type of a GraphQL query or mutation passed to `fetch`. For a plain query string, it's any plain object.

```typescript
type VariablesOf<Q> = Q extends { readonly __graphqlTypes?: { variables: infer TVariables } }
  ? TVariables
  : Record<string, unknown>;
```

**Used by:** [`fetch()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#fetch)

## VariantPrice

A variant's price for the customer.

```typescript
type VariantPrice = {
  taxRate: number;
  net: number;
  gross: number;
  currencyCode: string;
  taxInclusiveDisplay: boolean; // If true, show gross; otherwise net
};
```

**Used by:** [`ProductVariant`](#productvariant) (`price`), [`VariantPriceBreak`](#variantpricebreak)

## VariantPriceBreak

One price break (tier) for a variant: the price per unit from `quantity` upwards.

```typescript
type VariantPriceBreak = {
  quantity: number;
  price: VariantPrice;
  unitOfMeasure: string | null;
};
```

**Used by:** [`getPricingForVariant()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getpricingforvariant), [`ProductVariant`](#productvariant), [`ProductVariantPricing`](#productvariantpricing)

## Next steps

- [Methods](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md): Every window\.spark method, with the types it takes and returns.
- [Hooks](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md): The functions SparkLayer calls with a Cart, CartResults or the Spark object.
- [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md): Build an UpdateCart and handle the CartResults it returns.


---

# Events and components

URL: https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components

SparkLayer's web components, such as spark-pdp and spark-product-card, and the DOM events they dispatch, with each event.detail and an example of each.

SparkLayer's interfaces are web components: custom HTML elements you add to your theme. Some of them dispatch DOM events you can listen for, and you can dispatch one yourself to switch the drawer's tab.

## DOM events

| Event | When it fires | `event.detail` | Bubbles? |
| --- | --- | --- | --- |
| [`spark-variant-change`](#spark-variant-change) | The customer selects a variant in `spark-pdp` or `spark-product-card`. Dispatched on that element. | `{ product: Product; variant: ProductVariant }` | No: listen on each element. |
| [`spark-file-attachment-changed`](#spark-file-attachment-changed) | The list of files uploaded to a `spark-file-upload-field` changes. | `{ fileSize: number; fileName: string; gid: string }[] \| null` (`null` when every file is removed) | Yes, to `window`. |
| [`spark-file-attachment-failed`](#spark-file-attachment-failed) | A file fails to upload to a `spark-file-upload-field`. | `{ fileSize: number; fileName: string; errorCode: "unsupported-file-type" \| "file-too-large" \| "default" }` | Yes, to `window`. |
| [`view-update`](#view-update) | You dispatch it on `window` to switch an open drawer to a tab. | `{ view: DrawerUIState }` | You dispatch it with `bubbles: true`. |

### spark-variant-change

`event.detail.product` is a [`Product`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#product) and `event.detail.variant` a [`ProductVariant`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#productvariant); their `externalId` is your platform's ID. Add the listeners in `onReady`, once the elements are on the page.

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  onReady: async () => {
    for (const card of document.querySelectorAll('spark-product-card')) {
      card.addEventListener('spark-variant-change', (event) => {
        console.log(event.detail.product.externalId, event.detail.variant.externalId);
      });
    }
  },
};
```

See [Update the product image when a variant is selected](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md#update-the-product-image-when-a-variant-is-selected).

### spark-file-attachment-changed

```javascript title="Product page"
window.addEventListener('spark-file-attachment-changed', (event) => {
  const gids = (event.detail ?? []).map((file) => file.gid);
  document.querySelector('#shirt-design').value = JSON.stringify(gids);
});
```

See [Let customers upload a file](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#let-customers-upload-a-file) to attach the files to the cart.

### spark-file-attachment-failed

```javascript title="Product page"
window.addEventListener('spark-file-attachment-failed', (event) => {
  const { fileName, errorCode } = event.detail;
  console.warn(`${fileName} wasn't uploaded: ${errorCode}`);
});
```

### view-update

`view` is a [`DrawerUIState`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#draweruistate). To open a closed drawer, use [`openDrawer()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#opendrawer).

```javascript title="Switch the open drawer to the Cart tab"
window.dispatchEvent(
  new CustomEvent('view-update', {
    bubbles: true,
    composed: true,
    detail: { view: 'cart' },
  }),
);
```

See [Open the cart drawer](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#open-the-cart-drawer).

## Web components

`parent-id` is your platform's ID for the parent product. For each interface's display settings (attributes such as `show-sku`), see [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md).

| Element | What it renders | Key attributes | See |
| --- | --- | --- | --- |
| `<spark-pdp>` | The product detail interface, on product pages. | `parent-id` | [Product detail](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) |
| `<spark-product-card>` | The product card interface, wherever a product card appears. | `parent-id` | [Product card](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) |
| `<spark-product-matrix>` | Every variant in a grid, for products with two options. | `parent-id` | [Product matrix](https://docs.sparklayer.io/help/storefront/interfaces/product-matrix.md) |
| `<spark-product-price>` | The customer's price for a product, anywhere on the page. | `parent-id` | [Product price](https://docs.sparklayer.io/help/storefront/interfaces/product-price.md) |
| `<spark-product-rrp>` | The product's RRP. | `parent-id` | [Product price](https://docs.sparklayer.io/help/storefront/interfaces/product-price.md) |
| `<spark-file-upload-field>` | A file upload field for the product page. | `allowed-extensions` (a JSON array), `max-file-size` (bytes), `max-files`, `required` | [Let customers upload a file](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#let-customers-upload-a-file) |
| `<spark-drawer>` | The drawer (cart, account and other tabs). SparkLayer adds it when needed; use [`openDrawer()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#opendrawer) rather than adding it yourself. | – | [openDrawer()](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#opendrawer) |

```html title="Product page"
<spark-pdp parent-id="{{ product.id }}"></spark-pdp>

<spark-file-upload-field
  id="shirt-design-upload"
  allowed-extensions='["png", "jpg", "jpeg"]'
  max-files="1"
></spark-file-upload-field>
```

## Next steps

- [Events and analytics](https://docs.sparklayer.io/developers/javascript-sdk/events-and-analytics.md): Run your code from hooks and DOM events, and send B2B events to your analytics.
- [Products and pricing](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md): Swap the product image when a customer selects a variant.
- [Frontend integration](https://docs.sparklayer.io/developers/frontend.md): Add the product page interfaces and hide elements from B2B customers.


---

# Templates

URL: https://docs.sparklayer.io/developers/templates

Build custom SparkLayer invoice, quote and email templates in Liquid, using the currency, translate, ldate and country filters, sections and language files.

Templates set the design and wording of the PDFs and emails SparkLayer creates, such as invoices, quotes and purchase approval emails. They're written in [Liquid](https://shopify.github.io/liquid/), and each one receives the data listed under [Available data](#available-data).

## The templates

| Template | Type | What it's for |
| --- | --- | --- |
| invoice.liquid | PDF | The invoice |
| quote.liquid | PDF | The quote |
| limited-user-purchase-review\.liquid | Email | Sent when a [limited user](https://docs.sparklayer.io/help/glossary.md#limited-user) places a purchase that needs approving |
| limited-user-purchase-approve.liquid | Email | Sent when a limited user's purchase is approved |
| new-quote-notification-to-merchant.liquid | Email | Tells you a customer has asked for a quote |
| quote-assigned-notification-to-agent.liquid | Email | Tells a sales agent a quote has been assigned to them |
| purchase-history-message-notification-to-agent.liquid | Email | Tells a sales agent about a new message on an order or quote |
| purchase-history-message-notification-to-customer.liquid | Email | Tells a customer about a new message on an order or quote |
| email-header.liquid | Section | The header every email shares |
| email-footer.liquid | Section | The footer every email shares |

Only the templates above can be used. Any other files uploaded to a theme are discarded, including supporting files such as images and fonts.

### Create and upload a template

1. In the SparkLayer Dashboard, go to **Settings > Templates** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/theme)), or **SparkLayer Wholesale > Settings > Templates** in the Shopify app.
2. Click **Create template**. SparkLayer creates a template theme for you to edit.
3. Add only the files you'll change, and edit them in the SparkLayer editor. Click **Save** to create a revision. To go back, open a previous revision from the **Revisions** drop-down and save it.
4. For bigger changes, download the template as a ZIP file, work on it with your own tools, then zip it up and upload it.

A new template is empty, so it falls back to SparkLayer's core templates and language files until you add files to it. Once you add a file, it's no longer updated from the core templates: if a new feature changes a core template, copy the change into your file. See [Templates](https://docs.sparklayer.io/help/dashboard/settings.md#templates) in the Help Center for more. 

### Template markup and Liquid

Templates are written in [Liquid](https://shopify.github.io/liquid/) and have access to most Liquid tags and filters, plus the helper filters below.

Add styling in the template, in a `style` element or inline styles. All styles are inlined when the template is rendered, for better compatibility with email clients.

The email templates are tested in modern web-based email clients such as Gmail. Older email clients, such as desktop versions of Outlook, aren't supported. Test your custom email templates, because email clients often handle modern HTML and CSS badly.

### Filters and blocks

- [Currency](#currency)
- [Translate](#translate)
- [Localised date format](#localised-date-format)
- [Country from country code](#country-from-country-code)
- [Template sections](#template-sections)

### Currency

Use the `currency` filter for monetary values. It renders the currency with the right formatting for the locale.

```liquid title="Template"
{{ "9.99" | currency: "gbp" }}
```

```text title="Output"
£9.99
```

To change the currency formatting, pass one of these options:

- `display_none`
- `display_code`
- `display_symbol` (default)

```liquid title="Template"
{{ "9.99" | currency: "gbp", "display_code" }}
```

```text title="Output"
GBP 9.99
```

The filter also has a shorthand alias, `c`, which works the same way.

### Translate

Use the `translate` filter to translate text in a template. The theme needs a language file with the translation strings. See [Internationalisation and translations](#internationalisation-and-translations) for how to add language files.

```json title="en.json"
{
  "example": {
    "heading": "Welcome to SparkLayer!"
  }
}
```

```liquid title="Template"
{{ "example.heading" | translate }}
```

```text title="Output"
Welcome to SparkLayer!
```

The filter also has a shorthand alias, `t`, which works the same way.

To insert values into a string, add numbered slots to the string and pass the values as arguments to the filter:

```json title="en.json"
{
  "example": {
    "heading": "Dear ${1} of ${2}"
  }
}
```

```liquid title="Template"
{{ "example.heading" | translate: "Jeremy Sparks", "SparkLayer" }}
```

```text title="Output"
Dear Jeremy Sparks of SparkLayer
```

This filter translates using the store locale from the merchant data (`data.merchant`), falling back on the `en` translation file if no translation is found for the respective locale.

### Localised date format

Use the `ldate` filter to format dates for a locale. By default, it uses the store's locale from the merchant data (`data.merchant`). To use another locale, pass it as a parameter.

```liquid title="Template"
{{ "2024-10-22T16:18:02.196Z" | ldate }}
```

```text title="Output"
22/10/2024
```

With a locale:

```liquid title="Template"
{{ "2024-10-22T16:18:02.196Z" | ldate: "fr-CA" }}
```

```text title="Output"
2024-10-22
```

### Country from country code

Use the `country` filter to show a country name from its country code. This helps with address data, which stores the country code rather than the name.

```liquid title="Template"
{{ "gb" | country }}
```

```text title="Output"
United Kingdom
```

Country names are always returned in English, whatever the store's locale.

### Template sections

Use the `section` tag to include a section template. Only the section templates listed under [The templates](#the-templates) are supported; you can't add custom sections.

```liquid title="Template"
<main>
    {% section email-header %}
    <p>Content</p>
    {% section email-footer %}
</main>
```

```html title="Output"
<main>
    <header>
        <h1>Hello World</h1>
    </header>
    <p>Content</p>
    <footer>Copyright Year</footer>
</main>
```

## Internationalisation and translations

You can add language JSON files to a theme to translate its templates. Name each file with a language code (such as `en` or `fr`) that matches the locale used by your store. The translations in these files are available through the [translate](#translate) Liquid filter.

By default, the filter uses the store's locale. If your language files have no translation for a key, it falls back to SparkLayer's core language files, with `en` as the final fallback.

## Available data

Templates get their data through the `data` Liquid variable, for example `data.merchant.store_name`.

| Template | Top-level objects |
| --- | --- |
| invoice.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase), [settings](https://docs.sparklayer.io/developers/templates/template-objects.md#invoicesettings) |
| quote.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase) |
| limited-user-purchase-review\.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase) |
| limited-user-purchase-approve.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase) |
| new-quote-notification-to-merchant.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase) |
| quote-assigned-notification-to-agent.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase), [assignment\_details](https://docs.sparklayer.io/developers/templates/template-objects.md#assignmentdetails) |
| purchase-history-message-notification-to-agent.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase), [purchase\_history\_message](https://docs.sparklayer.io/developers/templates/template-objects.md#purchasehistorymessage) |
| purchase-history-message-notification-to-customer.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase), [purchase\_history\_message](https://docs.sparklayer.io/developers/templates/template-objects.md#purchasehistorymessage) |
| email-header.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant) |
| email-footer.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant) |

The data varies by template, but every template has the store details (`data.merchant`). [This object](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant) holds the store's general information, which you can change in the [SparkLayer Dashboard settings](https://docs.sparklayer.io/help/dashboard/settings.md).

## Next steps

- [Template objects](https://docs.sparklayer.io/developers/templates/template-objects.md): every object and property available to templates.
- [Templates in the Help Center](https://docs.sparklayer.io/help/dashboard/settings.md#templates): what merchants can change with templates.
- [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md): the languages SparkLayer supports.


---

# Template objects

URL: https://docs.sparklayer.io/developers/templates/template-objects

Properties of the objects available in SparkLayer Liquid templates, including Merchant, Purchase, LineItem, Customer, Address, Money and invoice content zones.

These are the SparkLayer objects you can use in [templates](https://docs.sparklayer.io/developers/templates.md) and invoice content zones. Which objects are available depends on the template: check the template's documentation to see what it receives.

Nested properties are shown with dot notation (for example `dates.created_at`), and `[]` marks an array item.

## Address

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `name` | `string` | The addressee's name | _-_ |
| `company` | `string` | The company name | _-_ |
| `address_line1` | `string` | Line 1 of the address | _-_ |
| `address_line2` | `string,null` | Line 2 of the address | _-_ |
| `city` | `string` | The city | _-_ |
| `region_code` | `string,null` | The region code, such as a state or county code | _-_ |
| `postal_code` | `string,null` | The postal code or postcode | _-_ |
| `country_code` | `string` | The country code. Use the [`country` filter](https://docs.sparklayer.io/developers/templates.md#country-from-country-code) to show the country name | _-_ |
| `phone` | `string,null` | The phone number | _-_ |

## Customer

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `id` | `string` | The customer's SparkLayer ID | _-_ |
| `title` | `string` | The customer's title | _-_ |
| `first_name` | `string` | The customer's first name | _-_ |
| `last_name` | `string` | The customer's last name | _-_ |
| `email` | `string` | The customer's email address | _-_ |
| `company_name` | `string,null` | The customer's company name | _-_ |
| `external_id` | `string` | - | _-_ |
| `accounting_id` | `string` | - | _-_ |

## ContentZone

Content zones are configured as part of the invoicing feature. They can contain Liquid variables, so handle them accordingly in your templates.

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `title` | `string,null` | The content zone's title | _-_ |
| `content` | `string,null` | The content zone's content, which can contain Liquid variables | _-_ |

## InvoiceSettings

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `content_zones.zone_1` | [ContentZone](#contentzone) | Invoice content zone 1 | _-_ |
| `content_zones.zone_2` | [ContentZone](#contentzone) | Invoice content zone 2 | _-_ |
| `content_zones.zone_3` | [ContentZone](#contentzone) | Invoice content zone 3 | _-_ |

## LineItem

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `custom_attributes.[].key` | `string` | A custom attribute's key | _-_ |
| `custom_attributes.[].value` | `string` | A custom attribute's value | _-_ |
| `identifiers.sku` | `string,null` | The product's SKU | _-_ |
| `name_child` | `string,null` | - | _-_ |
| `name_parent` | `string` | - | _-_ |
| `quantity` | `integer` | The quantity ordered | _-_ |
| `line_total` | [LineTotal](#linetotal) or `null` | The totals for the whole line | _-_ |
| `unit_total` | [UnitTotal](#unittotal) or `null` | The totals for one unit | _-_ |
| `image_url` | `string,null` | The URL of the product's image | _-_ |
| `product_slug` | `string,null` | - | _-_ |
| `rrp` | [Money](#money) or `null` | The recommended retail price (RRP) | _-_ |
| `barcode` | `string,null` | The product's barcode | _-_ |

## LineTotal

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `total_net` | [Money](#money) | The line total, excluding tax | _-_ |
| `discount_net` | [Money](#money) | The discount on the line, excluding tax | _-_ |
| `tax_rate` | `number` | The tax rate applied to the line | _-_ |

## Merchant

The merchant's store details.

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `address1` | `string,null` | Line 1 of the merchant's store address | _-_ |
| `address2` | `string,null` | Line 2 of the merchant's store address | _-_ |
| `base_currency` | `string,null` | The base currency used by the store | _USD,GBP_ |
| `city` | `string,null` | City of the merchant's store address | _-_ |
| `region` | `string,null` | Region code of the merchant's store address | _-_ |
| `country` | `string,null` | Country code of the merchant's store address | _GB_ |
| `email` | `string,null` | The merchant's email address | _-_ |
| `phone` | `string,null` | The merchant's store phone number | _-_ |
| `postcode` | `string,null` | Postcode of the merchant's store address | _-_ |
| `store_name` | `string,null` | The connected platform's store name | _-_ |
| `timezone` | `string,null` | The store's time zone | _-_ |
| `url` | `string,null` | The store's URL | _-_ |
| `locale` | `string,null` | The default locale of the store | _en,fr_ |

## Money

A monetary value.

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `amount` | `string` | The amount | _-_ |
| `currency` | `string` | The currency code | _GBP,USD_ |

## Package

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `line_items` | `array of` [LineItem](#lineitem) | The line items in the package | _-_ |
| `shipping_address` | [Address](#address) | The address the package is shipped to | _-_ |

## Purchase

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `currency_code` | `string` | The purchase's currency code | _-_ |
| `billing_address` | [Address](#address) | The billing address | _-_ |
| `customers.sparklayer` | [Customer](#customer) | The SparkLayer customer who placed the purchase | _-_ |
| `custom_fields.[].name` | `string` | A custom field's name | _-_ |
| `custom_fields.[].value` | `string,null` | A custom field's value | _-_ |
| `customer_reference` | `string,null` | The customer's own reference for the purchase | _-_ |
| `dates.created_at` | `string` | When the purchase was created | _-_ |
| `dates.updated_at` | `string` | When the purchase was last updated | _-_ |
| `dates.placed_at` | `string,null` | When the purchase was placed | _-_ |
| `dates.calculated_submitted_at` | `string,null` | - | _-_ |
| `identifiers.visible` | `string` | The purchase ID shown to customers | _-_ |
| `packages` | `array of` [Package](#package) | The purchase's packages, each with its line items and shipping address | _-_ |
| `line_items` | `array of` [LineItem](#lineitem) | The purchase's line items | _-_ |
| `subtotal` | [Money](#money) | The subtotal | _-_ |
| `tax` | [Money](#money) | The total tax | _-_ |
| `shipping_cost` | [Money](#money) | The shipping cost | _-_ |
| `calculated_total` | [Money](#money) | The calculated total | _-_ |
| `tax_lines` | `array of` [TaxLine](#taxline) | The tax lines that make up the total tax | _-_ |

## UnitTotal

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `total_net` | [Money](#money) | The unit price, excluding tax | _-_ |
| `total_gross` | [Money](#money) | The unit price, including tax | _-_ |
| `total_tax` | [Money](#money) | The tax on one unit | _-_ |
| `tax_rate` | `number` | The tax rate applied | _-_ |

## TaxLine

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `title` | `string` | The tax line's name | _-_ |
| `rate` | `number` | The tax rate | _-_ |
| `amount.number` | `string` | The tax amount | _-_ |
| `amount.currency` | `string` | The tax amount's currency code | _-_ |

## PurchaseHistoryMessage

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `body` | `string` | The message's text | _-_ |
| `created_at` | `string` | When the message was sent | _-_ |
| `customer` | [Customer](#customer) | The customer who sent the message | _-_ |

## AssignmentDetails

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `assigned_by` | [Customer](#customer) | Who assigned the quote | _-_ |
| `assigned_on` | `string` | When the quote was assigned | _-_ |

If a property doesn't behave as described here, [contact our support team](https://docs.sparklayer.io/help/support.md).

## Next steps

- [Templates](https://docs.sparklayer.io/developers/templates.md): the templates you can customise and the filters they can use.
- [Invoices](https://docs.sparklayer.io/help/ordering/invoices.md): the invoice PDF and its settings.


---

# Data and limits

URL: https://docs.sparklayer.io/developers/data

Reference for how SparkLayer stores extra product, customer and order data in metafields, and the recommended and hard limits on the data you send.

SparkLayer keeps some settings, such as a product's pack size or a customer's price lists, in [metafields](https://docs.sparklayer.io/help/glossary.md#metafields): extra fields on products, customers and orders in your eCommerce platform. Use these pages to look up the keys SparkLayer reads, and the limits to design your integration around.

- [Metafields](https://docs.sparklayer.io/developers/data/metafields.md): Every SparkLayer product, customer and order metafield key and type, such as `pack_size`, `rrp`, `price_lists` and `payment_on_account`, and how to auto-configure them.
- [Data limitations](https://docs.sparklayer.io/developers/data/data-limitations.md): Recommended and hard limits for SparkLayer data, including products, customers, customer groups, price lists, cart line items, addresses and discounts.


---

# Metafields

URL: https://docs.sparklayer.io/developers/data/metafields

Every SparkLayer product, customer and order metafield key and type, such as pack_size, rrp, price_lists and payment_on_account, and how to auto-configure them.

Metafields store extra information that your eCommerce platform doesn't usually capture. SparkLayer uses them for additional B2B data:

| Type | Used for |
| --- | --- |
| **Product metafields** | Configuring the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md), such as [pack sizes](https://docs.sparklayer.io/help/storefront/quantity-rules.md) and [RRP prices](https://docs.sparklayer.io/help/pricing/pricing-display.md) |
| **Customer metafields** | Adding customer information, such as [credit limits](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) |
| **Order metafields** | Adding [invoicing information](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) to an order, and importing order history |

This page lists every metafield SparkLayer supports. On Shopify, each one uses the namespace `sparklayer`, for example `sparklayer.pack_size`. For setting them up on your platform, see:

- [Shopify metafields and data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md)
- [BigCommerce metafields and data mapping](https://docs.sparklayer.io/help/platforms/bigcommerce/metafields.md)

## Automatically configure metafields

On Shopify, SparkLayer can create its metafield definitions for you.

1. In the [SparkLayer Dashboard](https://app.sparklayer.io/configuration/integrations/platform), go to **Integrations > Platform connection**.
2. In the **Configure metafields** section, click **Configure**. You'll see every metafield that can be configured for **Product** and **Customer** data.

Each metafield you enable is added to [Custom data](https://admin.shopify.com/settings/custom_data) in your Shopify admin and pinned, so it's easy to find when you edit products or customers.

![SparkLayer metafields pinned in Shopify's custom data settings](https://docs.sparklayer.io/images/shared/metafields-66d501.webp)

Metafields created this way are named `B2B - [name]`, for example `B2B - Pack Size`. To change or remove them, use [Custom data](https://admin.shopify.com/settings/custom_data) in your Shopify admin.

## Product metafields

Apply all product metafields at the variant level.

| Metafield | Key | Type |
| --- | --- | --- |
| **Recommended retail price (RRP).** Sets an RRP ("MSRP") price for a variant. See [pricing display](https://docs.sparklayer.io/help/pricing/pricing-display.md). | `rrp` | `json` |
| **Pack size.** Sets pack size rules for products, such as 6, 12 or 18. See [quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md). | `pack_size` | `integer` |
| **Minimum purchasable quantity (variant level).** The minimum quantity of the variant customers must buy. See [quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md). | `min_order_quantity` | `integer` |
| **Maximum purchasable quantity (variant level).** The maximum quantity of the variant customers can buy. See [quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md). | `max_order_quantity` | `integer` |
| **Minimum purchasable quantity (product level).** The minimum quantity customers must buy across all variants. See [quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md). | `min_order_parent_quantity` | `integer` |
| **Maximum purchasable quantity (product level).** The maximum quantity customers can buy across all variants. See [quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md). | `max_order_parent_quantity` | `integer` |
| **Reserve stock.** Reserves an amount of stock that isn't available for regular purchase, for example to hold inventory for specific customers, events or direct-to-consumer sales. See [stock display](https://docs.sparklayer.io/help/storefront/stock-display.md). | `reserve_stock_quantity` | `integer` |
| **Product visibility.** Whether a variant is visible on the storefront. If disabled, customers don't see the variant, even if it can still be bought in other ways. See [product display](https://docs.sparklayer.io/help/storefront/product-display.md). | `display` | `boolean` |
| **Purchasing.** Whether a variant can be added to the cart and bought. When disabled, the product stays visible but can't be bought, for example to showcase upcoming or unavailable items. See [product display](https://docs.sparklayer.io/help/storefront/product-display.md). | `sell` | `boolean` |
| **Customer group product rules.** B2B product rules, such as pack size and orderable quantities, for specific customer groups. Overrides the metafields above. See [product settings](https://docs.sparklayer.io/help/storefront/product-settings.md). | `settings` | `json` |
| **Reserved DTC stock quantity.** A stock quantity to reserve for your direct-to-consumer (DTC) customers. See [stock display](https://docs.sparklayer.io/help/storefront/stock-display.md). | `min_stock_level` | `integer` |
| **Restock date.** The date a product in pre-order status is expected to be available. See [stock display](https://docs.sparklayer.io/help/storefront/stock-display.md). | `restock_date` | `date` |
| **Stock location settings.** B2B stock settings, such as minimum stock level and restock date, for specific stock locations. See [stock display](https://docs.sparklayer.io/help/storefront/stock-display.md). | `stock_location_data` | `json` |

You can also set customer-specific product rules: see [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md).

## Customer metafields

| Metafield | Key | Type |
| --- | --- | --- |
| **Customer title.** The customer's title (such as Mr, Ms or Dr), for personalising invoices, emails and account records. See [account and addresses](https://docs.sparklayer.io/help/customers/account-and-addresses.md). | `title` | `single line text` |
| **Company name.** The name of the customer's company. See [account and addresses](https://docs.sparklayer.io/help/customers/account-and-addresses.md). | `company_name` | `single line text` |
| **Assigned group.** The customer group assigned to the customer. Overrides any tags assigned to the customer. | `group` | `single line text` |
| **Customer-specific price lists.** The price lists assigned to the customer. Overrides any price lists assigned to the customer group. See [customer pricing](https://docs.sparklayer.io/help/pricing/customer-pricing.md). | `price_lists` | `json`<br />`single_line_text` |
| **Invoice payment.** JSON settings that define whether the customer can pay by invoice, so approved customers can complete purchases without paying straight away. See [credit, net terms and invoicing](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md). | `payment_by_invoice` | `json` |
| **Credit limit and account balance.** The customer's credit limit and account balance. See [credit, net terms and invoicing](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md). | `payment_on_account` | `json` |
| **Accounting ID.** A unique accounting ID for the customer. See [account and addresses](https://docs.sparklayer.io/help/customers/account-and-addresses.md). | `accounting_id` | `single line text` |
| **Additional percentage discount.** A flat discount percentage applied on top of other discounted pricing. See [customer pricing](https://docs.sparklayer.io/help/pricing/customer-pricing.md). | `discount_percentage` | `single line text`<br />`integer`<br />`float` |
| **Sales agent groups.** The sales agent groups assigned to the customer, so dedicated representatives can manage the account. See [restricting which customers a sales agent can see](https://docs.sparklayer.io/help/sales-reps.md#restrict-which-customers-a-sales-agent-can-see). | `sales_agent_groups` | `list.single_line_text` |
| **Parent account.** Links the customer to a parent customer account, for businesses with multi-level accounts, sub-customers and centralised purchasing. See [company users](https://docs.sparklayer.io/help/customers/company-users.md). | `parent_customer_id` | `single line text` |
| **Customer role.** The customer's role in their company, used to apply permissions. See [company users](https://docs.sparklayer.io/help/customers/company-users.md). | `role` | `single line text` |
| **Default shipping address ID.** The shipping address to use by default for orders. See [account and addresses](https://docs.sparklayer.io/help/customers/account-and-addresses.md). | `shipping_address_id` | `single line text` |
| **Default billing address ID.** The billing address to use by default for orders. See [account and addresses](https://docs.sparklayer.io/help/customers/account-and-addresses.md). | `billing_address_id` | `single line text` |
| **Available shipping addresses.** JSON listing every shipping address available to the customer, for businesses with several delivery locations. See [account and addresses](https://docs.sparklayer.io/help/customers/account-and-addresses.md). | `available_shipping_address_ids` | `json` |

To use the advanced metafields, [speak to our team](https://docs.sparklayer.io/help/support.md) about how they work.

## Order metafields

| Metafield | Key | Type |
| --- | --- | --- |
| **Invoice link.** A URL to the order's invoice, so customers can get to digital invoices quickly. See [credit, net terms and invoicing](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md). | `invoice_url` | `url`<br />`list.url`<br />`file_reference`<br />`list.file_reference` |
| **Order import.** Set to `true` to import a historic order into SparkLayer, so customers see it in their order history. See [importing order history](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#import-order-history-into-sparklayer). | `order_import` | `boolean` |
| **Visible ID.** A custom order ID shown instead of the platform's order number, for example your ERP order number, so the ID is the same in every system. Shopify only. See [setting a custom order number](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#set-a-custom-order-number). | `visible_id` | `single line text` |

## Next steps

- [Shopify metafields and data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md): set up and fill in metafields on Shopify.
- [Data limitations](https://docs.sparklayer.io/developers/data/data-limitations.md): limits on the data you send to SparkLayer.
- [Building integrations](https://docs.sparklayer.io/developers/building-integrations.md): how data flows between SparkLayer and your other systems.


---

# Data limitations

URL: https://docs.sparklayer.io/developers/data/data-limitations

Recommended and hard limits for SparkLayer data, including products, customers, customer groups, price lists, cart line items, addresses and discounts.

SparkLayer is built to scale, but there are limits on how much data it can process without affecting performance. They matter most if you have large data sets, such as a high volume of price lists.

| Area | Recommended maximum | Hard limit (performance implications) |
| --- | --- | --- |
| **Customer groups** | 50 | 100 |
| **Products** | 50,000 | 100,000 |
| **Customers** | 100,000 | 250,000 |
| **Customer sub-accounts**\* | 250 | 250 |
| **Customer addresses**\* | 250 | 500 |
| **Sales agents** | Not applicable | None |
| **Sales agent groups** | 1,000 | 2,500 |
| **Price lists** | 15,000 | 25,000 |
| **Customer carts** | Unlimited (stored for up to 3 months after the last change) | |
| **Line items in a cart** | 250 | 250 |
| **Discounts** | 50 unique discounts, 15 concurrent | 100 unique discounts, 25 concurrent |

\*Limit per customer

## Platform limitations

For limitations specific to a platform, see [Integrations](https://docs.sparklayer.io/help/integrations.md).

## Next steps

- [Metafields](https://docs.sparklayer.io/developers/data/metafields.md): the extra product, customer and order data SparkLayer stores.
- [Architecture](https://docs.sparklayer.io/developers/architecture.md): how SparkLayer connects to your other systems.


---

# SparkLayer Ignite

URL: https://docs.sparklayer.io/ignite

SparkLayer Ignite connects any eCommerce platform or CMS to SparkLayer. Covers the data flow, platform connection, data sync and the endpoints you must build.

**SparkLayer Ignite** is a framework for connecting any eCommerce platform or CMS to SparkLayer, from the B2B self-service ordering experience on the storefront to SparkLayer's B2B pricing engine. You build a service, the Ignite integration, that SparkLayer calls to work with your platform.

## Use cases

The most common use is alongside an eCommerce platform or content management system (CMS) that SparkLayer doesn't integrate with. For example, a platform may have very limited B2B functionality that isn't practical to build natively. Connecting it to SparkLayer through Ignite, for example with a custom application, adds the B2B features quickly.

To get access to Ignite, [complete the application form](https://share-eu1.hsforms.com/1ZSI9nEs5SwGyrx9kvWIA2wfkn6z). Our team reviews each application to check SparkLayer is a good match for the use case, both technically and strategically.

## Before starting

These docs cover the principles and concepts you need to build an Ignite integration: connecting a platform, synchronising data and implementing the endpoints SparkLayer calls. To get familiar with how SparkLayer works first, read:

| Area | Notes |
| --- | --- |
| [The SparkLayer Frontend](https://docs.sparklayer.io/help/storefront.md) | A JavaScript overlay that replaces specific parts of an eCommerce website with wholesale ordering features. |
| [The SparkLayer Dashboard](https://docs.sparklayer.io/help/dashboard.md) | The web app where merchants manage every part of their SparkLayer setup. |

## Key principles

### Understanding the data flow

Understanding how data flows between SparkLayer and your platform is central to building an integration. This diagram shows the key flows:

| Platform | Data | Direction | SparkLayer |
| --- | --- | --- | --- |
| Configuration (integration) | Platform connection settings | SparkLayer → integration | Platform connection |
| Products | Full product data | Platform → SparkLayer | Products |
| Orders | Order sync, plus shipments, refunds and cancellations | Platform → SparkLayer | Orders |
| Customers + addresses | Creation, updates and deletes | Platform → SparkLayer | Customers + addresses |
| Checkout / order | Tax and shipping calculations, checkouts and orders | SparkLayer → platform | Checkout |
| Customers + additional attributes | Creating, updating and deleting a customer | SparkLayer → platform | Customer sub-accounts |
| Logged-in customer (integration) | The customer's session | Integration → SparkLayer | FE authentication |
| Validate token | Token validation | Both directions | FE authentication |

### Platform connection

A **platform connection** links an eCommerce platform store to a SparkLayer site. SparkLayer calls two endpoints on your integration: one when a platform is **connected**, and one when it's **disconnected**. See [Platform connection](https://docs.sparklayer.io/ignite/platform-connection.md).

### Data sync overview

SparkLayer needs data from the platform to work. A full sync runs when SparkLayer is first installed. After that, webhooks (or other platform events) should drive incremental updates, with the option to run a full sync again if there are issues. Log data sync issues with the [Sync Logging API](https://docs.sparklayer.io/developers/api/sync-log.md), so merchants can review them in the [SparkLayer Dashboard](https://app.sparklayer.io). The data includes:

| Area | Details |
| --- | --- |
| Product data | SparkLayer needs a basic level of product data to be synced across for the [frontend widgets](https://docs.sparklayer.io/help/storefront.md) to operate. |
| Customer data | SparkLayer needs a basic level of customer data to be synced across for the [frontend widgets](https://docs.sparklayer.io/help/storefront.md) to operate. |
| Order data | SparkLayer needs order data to be synced across for the [frontend widgets](https://docs.sparklayer.io/help/storefront.md) to show order data within the account section. |
| Store settings | SparkLayer needs to know the base currency of the store. |

See [Data sync](https://docs.sparklayer.io/ignite/data-sync.md).

### Endpoints

SparkLayer calls these endpoints in real time, when a customer does something on the storefront. The [endpoint reference](https://docs.sparklayer.io/ignite/api.md) gives the request and response bodies for each.

| Area | Details |
| --- | --- |
| Create, update and delete addresses | Customers manage their addresses in the [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md). |
| Fetch shipping and tax for an order | As the customer goes through checkout in the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md), SparkLayer shows shipping rates and tax for the order. |
| Create and delete sub-account customers | Customers create and delete the customers who are their sub-accounts on the storefront. |
| Create a checkout for upfront orders | When a customer places an order that needs [upfront payment](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md#payment-methods) through the platform (for example by credit card), SparkLayer sends them to the platform's checkout to pay. This can be the standard platform checkout, and doesn't need to include discounts and gift cards. |
| Create an order for orders paid offline | When a customer places an order that [doesn't need payment](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md#payment-methods) at checkout, SparkLayer creates the order on the platform. |

See the [Endpoints overview](https://docs.sparklayer.io/ignite/endpoints-overview.md).

### Things to know

- These docs don't cover billing or SparkLayer Dashboard logic.
- SparkLayer supports a single storefront per SparkLayer environment.
- SparkLayer supports simple option products only: complex bundles aren't supported.

## Next steps

1. [Platform connection](https://docs.sparklayer.io/ignite/platform-connection.md): handle a merchant connecting and disconnecting your platform.
2. [Authentication](https://docs.sparklayer.io/ignite/authentication.md): verify the customers signed in to your platform.
3. [Data sync](https://docs.sparklayer.io/ignite/data-sync.md): sync products, customers, orders and settings to SparkLayer.
4. [Endpoints overview](https://docs.sparklayer.io/ignite/endpoints-overview.md): every endpoint your integration implements.


---

# Platform connection

URL: https://docs.sparklayer.io/ignite/platform-connection

Handle new and removed Ignite platform connections, whether started from a platform app store or the SparkLayer Dashboard, including redirect_url and full sync.

A **platform connection** links an eCommerce platform store to a SparkLayer site. SparkLayer calls **two endpoints** on your integration: one when a platform is connected, and one when it's removed. A new connection can start from the eCommerce platform or from the SparkLayer Dashboard, and your integration needs to support both flows.

## Platform connection flows

### Initiated through the eCommerce platform

The merchant starts the connection from the platform's app store (or similar), for example by installing the SparkLayer app on BigCommerce or Shopify. This flow only applies if your platform supports third-party apps.

This flow uses the **SparkLayer Dashboard API** to register the user with SparkLayer, create a platform connection between the platform and a SparkLayer site, and get the site's onboarding progress. Its documentation isn't public, but we can provide it on request.

1. The merchant installs the SparkLayer app on their store.
2. Your integration stores the store's credentials and other data it needs, usually the store identifier and the platform's API access token or credentials.
3. The SparkLayer app on the platform shows the user a SparkLayer registration page. To register the user, call the Dashboard API's user registration endpoint.
4. When registration succeeds, SparkLayer returns the site environment and Site ID. Use them to call the Dashboard API's site platform connection endpoint, which links the store to the new SparkLayer site.
5. SparkLayer calls your integration's [Connect a platform](https://docs.sparklayer.io/ignite/api/new-platform-connection.md) endpoint with the Site ID and credentials. Store them and run the connection completion actions, such as a full data sync.
6. The connection is complete. In the platform's SparkLayer app, show the user the SparkLayer onboarding steps, with links to the SparkLayer Dashboard and the Help Center. Get the onboarding progress from the Dashboard API's onboarding steps endpoint.

### Initiated through the SparkLayer Dashboard

The merchant starts the connection from the eCommerce platform page of an existing SparkLayer site in the SparkLayer Dashboard (**Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app). 

1. SparkLayer calls your integration's [Connect a platform](https://docs.sparklayer.io/ignite/api/new-platform-connection.md) endpoint with the SparkLayer site and credentials.
2. Your integration stores this data and returns a `redirect_url`, where the merchant installs the SparkLayer app on the platform.
3. Once the app is installed, your integration stores the store's credentials and other data it needs.
4. Your integration now has both the SparkLayer and the platform data, so the connection is complete and it can start actions such as a full data sync.
5. Show the user the SparkLayer onboarding steps and progress, from the Dashboard API's onboarding steps endpoint.

## Platform connection endpoints

SparkLayer calls these endpoints to tell your integration about a new or removed platform connection.

### New platform connection

[Connect a platform](https://docs.sparklayer.io/ignite/api/new-platform-connection.md) (`POST /v1/{siteEnv}/{siteId}`) records the new connection, and runs the completion actions if the connection is complete.

The request body includes:

| Field | Description |
| --- | --- |
| `store_id` | The store's ID on the platform |
| `spark_api_client_id` and `spark_api_client_secret` | API credentials your integration uses to call the [SparkLayer API](https://docs.sparklayer.io/developers/api.md) for this site |
| `extra_config`, `magento_*` | Platform-specific credentials for WooCommerce and Magento |

Respond with:

- `201` and a `redirect_url` when the connection is pending: the SparkLayer Dashboard redirects the merchant there to install the SparkLayer app on the platform
- `204` when the app is already installed and the connection is now active

Once the connection is complete (your integration has the SparkLayer and platform configuration and credentials, and can start syncing data):

1. Register any data change webhooks with the platform, if it has them.
2. Sync the store settings from the platform to the SparkLayer API.
3. Start a full sync of customers and products.

**Important considerations:**

- The connection may not be complete when SparkLayer calls this endpoint: for example, when the connection starts in the SparkLayer Dashboard and the merchant still has to finish it on the platform. In that case, return a `redirect_url` to the platform's SparkLayer installation page, where the merchant links their store to the pending connection.
- The endpoint must be idempotent, because SparkLayer may call it more than once. If the connection is already established, re-trigger the completion actions safely.

### Remove platform connection

[Disconnect a platform](https://docs.sparklayer.io/ignite/api/remove-platform-connection.md) (`DELETE /v1/{siteEnv}/{siteId}`) should:

- Stop processing any syncs
- [Delete the store's sync logs](https://docs.sparklayer.io/developers/api/sync-log/delete-a-stores-sync-logs.md)
- Delete the connection data stored by your integration

## Authentication between SparkLayer and your integration

**Calls from your integration to SparkLayer.** Use the `spark_api_client_id` and `spark_api_client_secret` from the connect request to get OAuth access tokens, as described in [Authentication](https://docs.sparklayer.io/developers/authentication.md). Tokens are short-lived, so store them with the connection data and refresh them when they expire.

**Calls from SparkLayer to your integration.** The Ignite spec lists `401 Auth Failure` responses for these endpoints, but doesn't define how SparkLayer authenticates its requests. 

## Next steps

- [Authentication](https://docs.sparklayer.io/ignite/authentication.md): verify customers signed in to your platform.
- [Data sync](https://docs.sparklayer.io/ignite/data-sync.md): the full sync to run once the connection is complete.


---

# Ignite authentication

URL: https://docs.sparklayer.io/ignite/authentication

How Ignite verifies platform customer sessions: SparkLayer passes a token such as a BigCommerce JWT to /authentication/verify and issues an access token.

When a customer signs in to their account on the eCommerce platform, SparkLayer needs to authenticate them too. To avoid making customers sign in twice (to the platform and to SparkLayer), some platforms let third parties such as SparkLayer authenticate a signed-in customer. These mechanisms differ between platforms, so Ignite defines one generic endpoint, [Verify storefront authentication](https://docs.sparklayer.io/ignite/api/verify-authentication.md), that receives the authentication data to verify.

This diagram shows how the authentication data moves from the storefront to your Ignite integration.

Ignite authentication sequence:

1. Front end → SparkLayer API: `POST /api/v1/ignite/authentication/verify`
2. SparkLayer API → Ignite API: `POST /authentication/verify`
3. The Ignite API verifies the authentication data.
4. Ignite API → SparkLayer API: the customer ID.
5. The SparkLayer API generates an access token for that customer ID.
6. SparkLayer API → front end: the access token.

## What your integration does

SparkLayer sends `POST /v1/{siteEnv}/{siteId}/authentication/verify` with the authentication data in the `data` property of the request body.

1. Verify the data, using whatever mechanism your platform provides.
2. Work out which customer it belongs to: it must be possible to derive the customer's platform ID from the data.
3. Respond with `200` and the customer's platform ID in `customer.external_id`. If the data can't be verified, respond with an error.

SparkLayer then uses the customer ID you return to generate an access token for that customer, and returns it to the customer's browser. The browser uses this access token for every later request to the SparkLayer API.

## BigCommerce example

When a B2B customer has signed in to a BigCommerce store:

1. SparkLayer's JavaScript in the customer's browser calls BigCommerce's [current customer endpoint](https://developer.bigcommerce.com/docs/storefront-auth/current-customer#get-current-customer), which returns a JSON Web Token (JWT).
2. The browser passes the JWT to SparkLayer's API.
3. SparkLayer passes the JWT to the Ignite service for BigCommerce at `/v1/{siteEnv}/{siteId}/authentication/verify`. Delegating verification keeps platform-specific code out of SparkLayer's core API.
4. The Ignite service verifies the token and returns the customer's BigCommerce ID.
5. SparkLayer generates an access token for that customer and returns it to the browser.

## Next steps

- [Data sync](https://docs.sparklayer.io/ignite/data-sync.md): sync products, customers, orders and settings to SparkLayer.
- [Verify storefront authentication](https://docs.sparklayer.io/ignite/api/verify-authentication.md): the endpoint's full request and response.


---

# Ignite data sync

URL: https://docs.sparklayer.io/ignite/data-sync

Sync products, pricing, customers, orders and store settings from your platform to SparkLayer with full syncs, webhook-driven updates and the sync-log API.

Data sync brings data from your platform, such as an eCommerce platform, into SparkLayer. Merchants see the data in the [SparkLayer Dashboard](https://docs.sparklayer.io/help/dashboard.md), and the [SparkLayer Frontend](https://docs.sparklayer.io/help/storefront.md) uses it to power the wholesale ordering experience: which customers SparkLayer is enabled for, what pricing they see, and their order history.

## When data sync happens

A full data sync runs:

- When the app is installed
- When data is inconsistent and needs refreshing. SparkLayer calls your integration's [Trigger a data sync](https://docs.sparklayer.io/ignite/api/trigger-a-data-sync.md) endpoint when someone clicks the manual sync buttons for products and customers in the SparkLayer Dashboard. This is only available to internal staff, such as SparkLayer support.

After that, partial updates keep data in sync, driven by webhooks or other events from the eCommerce platform.

### Important considerations

| Area | Notes |
| --- | --- |
| Queueing and retry | Retry partial sync events if they fail, so the platform stays stable and reliable. |
| Performance | Design the service so heavy use of our API doesn't affect it, and make as few updates as possible. For example, for a product update, fetch the product and its stock levels and only update what's changed. |
| Reporting | Log the last updated date and the last full sync with the [Sync Logging API](https://docs.sparklayer.io/developers/api/sync-log.md), as described in [Logging sync issues](#logging-sync-issues). |
| Issue logging | Handle any issues during the sync and log them with the Sync Logging API, so merchants can see them in the SparkLayer Dashboard. For example, a product variant with no SKU, or a customer address with an empty first line. |

## Sync endpoints in the Ignite spec

The [Ignite endpoint reference](https://docs.sparklayer.io/ignite/api.md) defines these data sync endpoints on your integration, which SparkLayer calls:

| Endpoint | Method and path | Purpose (from the spec) |
| --- | --- | --- |
| [List entities for a sync](https://docs.sparklayer.io/ignite/api/list-entities.md) | `GET /v1/{siteEnv}/{siteId}/sync/{syncDataType}` | During a full sync, SparkLayer pages through every entity of the type: return one page of entity IDs and a `next_page` value, and an empty `next_page` to end the sync. |
| [Fetch an entity](https://docs.sparklayer.io/ignite/api/fetch-entity.md) | `POST /v1/{siteEnv}/{siteId}/sync/{syncDataType}/{entityId}` | Fetch one entity from the platform, by its platform ID, as SparkLayer customer, product, purchase or stock data. |
| [Trigger a data sync](https://docs.sparklayer.io/ignite/api/trigger-a-data-sync.md) | `POST /v1/{siteEnv}/{siteId}/status/{syncDataType}` | Lets internal users, such as support staff, trigger a manual sync outside the standard process. |

`syncDataType` is one of `customers`, `products`, `purchases` or `stock`.

### How data reaches SparkLayer

SparkLayer pulls the data: during a sync, it lists and fetches customers, products, purchases and stock from your integration with the endpoints above. Stock levels and orders can also be pushed to SparkLayer's [Stock](https://docs.sparklayer.io/developers/api/stock.md) and [Purchasing](https://docs.sparklayer.io/developers/api/purchasing.md) APIs, for example as webhook-driven updates. Products and customers can only reach SparkLayer through **Fetch an entity**: the public API has no endpoints to create them.

## Types of data

The data to sync includes products, pricing, customers, orders and store settings.

### Products

Sync these product fields from the platform:

- `title`
- `slug`
- `external_id`: the platform's product ID
- `variants`
  - `external_id`: the platform's variant ID
  - `sku`
  - `weight_in_grams`
  - `position`
  - `cart_image_url`
  - `options`
  - `status`: `live` when the product is live, and `discontinued` when the product is deleted

SparkLayer fetches products from your integration with [Fetch an entity](https://docs.sparklayer.io/ignite/api/fetch-entity.md), as product data.

Stock levels, from `inventory_level`, are fetched with Fetch an entity as stock data. You can also push them to the SparkLayer Stock API with the [update stock levels endpoint](https://docs.sparklayer.io/developers/api/stock/update-stock-levels.md).

> **Extending the product object with B2B attributes**
>
> If your platform can store extra data, such as attributes (ideally on the variant), it's useful to sync these too:
>
> - `rrp`
> - `settings`
> - `restock_date`: belongs on the stock record, but can be taken from the variant

### Pricing

Sync product pricing to the [SparkLayer Pricing API](https://docs.sparklayer.io/developers/api/pricing.md).

Create at least one price list containing the default price of every product on the platform, named after the platform, such as "BigCommerce Price". Create it when the platform is connected, and update its prices whenever products sync. Create it with `source` set to `integration`.

### Customers

Sync customers and their addresses:

- `external_id`: the platform's customer ID
- `email`
- `first_name`
- `last_name`
- `company_name`
- `send_invite`
- `addresses`

SparkLayer fetches customers from your integration with [Fetch an entity](https://docs.sparklayer.io/ignite/api/fetch-entity.md), as customer data.

> **Extending the customer object with B2B attributes**
>
> If your platform can store extra data, such as attributes, it's useful to sync these too. `group` can also come from another field, such as a customer group on the platform.
>
> - `group`
> - `accounting_id`
> - `sales_agent_groups`
> - `price_lists`
> - `discount_percentage`
> - `payment_on_account`
> - `parent_customer_id`

### Orders

Orders are fetched with Fetch an entity as purchase data. You can also push them with the Purchasing API's [create or update a purchase endpoint](https://docs.sparklayer.io/developers/api/purchasing/create-update-purchase.md), including order creation, amendments and shipments.

For SparkLayer orders, always use the `sparklayer` purchase identifier when you create or update purchases. Other parts of SparkLayer may already have created a purchase for the order without knowing its other identifiers, such as the platform order ID. If you update that purchase with an identifier it wasn't created with, you get a `409 Conflict` error.

It's also useful to sync historical orders that weren't placed through SparkLayer but already exist on the eCommerce platform. For these, it's fine to create the purchase with the `platform` identifier: there's no SparkLayer identifier and no conflicting purchase. Merchants start a historical order import by setting the order import metafield on each order; see [Import order history into SparkLayer](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#import-order-history-into-sparklayer).

### Store settings

When the platform is connected, and whenever the relevant settings change on the eCommerce platform, sync these store settings:

- Base currency: send it with the [update global setting endpoint](https://docs.sparklayer.io/developers/api/core/update-global-setting.md), with the setting key `baseCurrency`.

## Logging sync issues

Report customer and product sync timestamps and errors with the [Sync Logging API](https://docs.sparklayer.io/developers/api/sync-log.md), so merchants can see them in the SparkLayer Dashboard and act on them.

### Full data synchronisation (including initial synchronisation)

Record a full sync with [Record a full sync](https://docs.sparklayer.io/developers/api/sync-log/update-sync-logs-with-a-full-sync.md) (`PUT`). It sets `started_full_sync` and `last_full_sync`, and replaces all previously logged errors with the ones you send.

- **Keep each error's `external_id` unique**, so errors aren't overwritten or resolved by mistake.
- **For a quick, synchronous sync**, send one `PUT` when it finishes, with `started_full_sync`, `last_full_sync` and all the errors.
- **For a long or asynchronous sync**, you won't have every error in one request:
  1. When the sync starts, send a `PUT` with `started_full_sync`. A timestamp you leave out is cleared, so `last_full_sync` is cleared until the sync finishes.
  2. As items sync, record errors (and errors that are now resolved) with [Record a partial sync](https://docs.sparklayer.io/developers/api/sync-log/update-sync-logs-with-a-partial-sync.md) (`PATCH`).
  3. When the whole sync has finished, send a `PATCH` with `last_full_sync` (and the required `last_partial_sync`).
- **If items sync in separate application instances** (for example through a queue), only set `last_full_sync` once every item has synced. The Sync Logging API doesn't track this, so your integration needs to keep track of the items synced and remaining.

### Partial synchronisation

Record a partial sync whenever an individual item syncs, for example when a product or customer is updated on the store and the change is synced to SparkLayer. Use [Record a partial sync](https://docs.sparklayer.io/developers/api/sync-log/update-sync-logs-with-a-partial-sync.md) (`PATCH`). It:

- Keeps the errors already logged
- Adds any new errors
- Resolves errors for the platform IDs you list in `successfully_synced`

Partial sync timestamps are only saved once a full sync has been recorded.

### Deleting sync logs

A full sync clears the previous errors, so you don't normally need to delete sync logs. If a store uninstalls SparkLayer, delete its sync logs with [Delete all sync logs](https://docs.sparklayer.io/developers/api/sync-log/delete-a-stores-sync-logs.md).

## Next steps

- [Endpoints overview](https://docs.sparklayer.io/ignite/endpoints-overview.md): every endpoint your integration implements.
- [Sync Logging API](https://docs.sparklayer.io/developers/api/sync-log.md): the endpoints for recording syncs and errors.


---

# Endpoints overview

URL: https://docs.sparklayer.io/ignite/endpoints-overview

Every endpoint an Ignite integration implements, for platform connection, customers, addresses, checkout, data sync, metafields and authentication.

These are the endpoints your Ignite integration implements for SparkLayer to call. Every path starts with `/v1/{siteEnv}/{siteId}`, where `siteEnv` is the SparkLayer environment (such as `live`) and `siteId` is the merchant's SparkLayer Site ID. For each endpoint's parameters, request body and responses, see the [Ignite endpoint reference](https://docs.sparklayer.io/ignite/api.md).

## Platform connection

| Endpoint | Method and path | Purpose |
| --- | --- | --- |
| [Connect a platform](https://docs.sparklayer.io/ignite/api/new-platform-connection.md) | `POST /v1/{siteEnv}/{siteId}` | Called when a platform is connected to SparkLayer, either from the SparkLayer Dashboard or when a connection started externally (for example through the platform's SparkLayer app) is complete. The request includes the SparkLayer site environment and ID, and the API credentials. |
| [Disconnect a platform](https://docs.sparklayer.io/ignite/api/remove-platform-connection.md) | `DELETE /v1/{siteEnv}/{siteId}` | Called when a platform is disconnected from SparkLayer. Cancel any data syncs and clean up the connection data in your integration. |

See [Platform connection](https://docs.sparklayer.io/ignite/platform-connection.md) for the full requirements.

## Customers

| Endpoint | Method and path | Purpose |
| --- | --- | --- |
| [Create or update a customer](https://docs.sparklayer.io/ignite/api/create-update-a-customer.md) | `PUT /v1/{siteEnv}/{siteId}/customers` | Create or update a customer on the eCommerce platform. Use the customer's email address to find them on the platform. |

## Customer sub-accounts

Sub-accounts need customer accounts on the eCommerce platform, which give SparkLayer the same layer of authentication as other accounts. Customers manage their sub-accounts in the frontend interfaces.

| Endpoint | Method and path | Purpose |
| --- | --- | --- |
| [Create a sub-account](https://docs.sparklayer.io/ignite/api/create-a-new-customer-sub-account.md) | `POST /v1/{siteEnv}/{siteId}/sub-accounts` | Create a customer on the platform and mark it as a sub-account of its parent. |
| [Update a sub-account](https://docs.sparklayer.io/ignite/api/update-an-existing-customer-sub-account.md) | `PATCH /v1/{siteEnv}/{siteId}/sub-accounts/{customer_external_id}` | Change a sub-account's first name, last name and role (not its email address). |
| [Delete a sub-account](https://docs.sparklayer.io/ignite/api/remove-a-customer-sub-account.md) | `DELETE /v1/{siteEnv}/{siteId}/sub-accounts/{customer_external_id}` | Remove a sub-account so it can no longer act for the parent account. |

## Customer addresses

Customers create, update and delete their addresses in the frontend interfaces.

| Endpoint | Method and path | Purpose |
| --- | --- | --- |
| [Create a customer address](https://docs.sparklayer.io/ignite/api/create-a-new-customer-address.md) | `POST /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses` | Create an address for a customer on the platform. |
| [Update a customer address](https://docs.sparklayer.io/ignite/api/update-a-customer-address.md) | `PUT /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses/{customer_address_external_id}` | Update a customer address on the platform. |
| [Delete a customer address](https://docs.sparklayer.io/ignite/api/remove-a-customer-address.md) | `DELETE /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses/{customer_address_external_id}` | Remove a customer address from the platform. |

## Checkout

| Endpoint | Method and path | Purpose |
| --- | --- | --- |
| [Calculate tax and shipping](https://docs.sparklayer.io/ignite/api/calculate-tax-and-shipping.md) | `POST /v1/{siteEnv}/{siteId}/checkout/calculate` | Called at the final step of checkout to show the customer tax and the available shipping methods. |
| [Complete checkout](https://docs.sparklayer.io/ignite/api/complete-checkout.md) | `POST /v1/{siteEnv}/{siteId}/checkout/complete` | Called when the customer completes the order. For upfront payment, return a URL to the platform's checkout; otherwise, create the order and return its ID. |

The checkout for upfront payment can be the standard platform checkout, and doesn't need to include discounts and gift cards.

**Important considerations:**

- SparkLayer prices are always tax exclusive. If the platform ever needs checkout prices with tax included, add the tax to the prices SparkLayer sends to the checkout endpoints.
- In the same way, if the shipping prices the platform calculates include tax, account for it, because SparkLayer works with tax-exclusive prices.
- Mark carts, checkouts and orders that your integration creates or updates as coming from SparkLayer, for example with an `external_id` or `source` parameter, or a metafield. Your order sync then uses this to know which orders to sync to SparkLayer.
- Store all the data SparkLayer sends to the checkout endpoints on the platform's cart, checkout or order. Map it to native fields where possible (such as the customer ID or additional order information); use metafields and attributes for data with no native field.

## Data sync

| Endpoint | Method and path | Purpose |
| --- | --- | --- |
| [List entities for a sync](https://docs.sparklayer.io/ignite/api/list-entities.md) | `GET /v1/{siteEnv}/{siteId}/sync/{syncDataType}` | Called during a full sync to page through every entity of a type. |
| [Fetch an entity](https://docs.sparklayer.io/ignite/api/fetch-entity.md) | `POST /v1/{siteEnv}/{siteId}/sync/{syncDataType}/{entityId}` | Fetch one entity from the platform. |
| [Trigger a data sync](https://docs.sparklayer.io/ignite/api/trigger-a-data-sync.md) | `POST /v1/{siteEnv}/{siteId}/status/{syncDataType}` | Lets internal staff trigger a manual sync from the SparkLayer Dashboard when data needs refreshing. |

See [Data sync](https://docs.sparklayer.io/ignite/data-sync.md) for what to sync and when.

## Metafield configuration

| Endpoint | Method and path | Purpose |
| --- | --- | --- |
| [Get metafield configuration](https://docs.sparklayer.io/ignite/api/get-metafield-configuration.md) | `GET /v1/{siteEnv}/{siteId}/metafield-configuration` | Return every SparkLayer metafield key the platform supports, and whether each one is configured. |
| [Enable a metafield](https://docs.sparklayer.io/ignite/api/enable-a-metafield.md) | `POST /v1/{siteEnv}/{siteId}/metafield-configuration/enable` | Enable a metafield key on the platform. |

See [Metafields](https://docs.sparklayer.io/developers/data/metafields.md) for the SparkLayer metafield keys.

## Authentication

| Endpoint | Method and path | Purpose |
| --- | --- | --- |
| [Verify storefront authentication](https://docs.sparklayer.io/ignite/api/verify-authentication.md) | `POST /v1/{siteEnv}/{siteId}/authentication/verify` | Verify authentication data from the storefront, such as a JWT, and return the customer's platform ID. |

See [Authentication](https://docs.sparklayer.io/ignite/authentication.md) for how this fits into sign-in.

## Next steps

- [Ignite endpoint reference](https://docs.sparklayer.io/ignite/api.md): each endpoint's parameters, request body and responses.
- [Platform connection](https://docs.sparklayer.io/ignite/platform-connection.md): the first endpoints SparkLayer calls.


---

# Ignite endpoints

URL: https://docs.sparklayer.io/ignite/api

Reference for the endpoints your Ignite service implements for SparkLayer to call: platform connection, customers, addresses, checkout, sync and authentication.

This reference lists every endpoint your Ignite integration implements, with its parameters, request body and responses. For what each one is for, see the [Endpoints overview](https://docs.sparklayer.io/ignite/endpoints-overview.md).

- [POST Connect a platform](https://docs.sparklayer.io/ignite/api/new-platform-connection.md)
- [DELETE Disconnect a platform](https://docs.sparklayer.io/ignite/api/remove-platform-connection.md)
- [PUT Create or update a customer](https://docs.sparklayer.io/ignite/api/create-update-a-customer.md)
- [POST Create a sub-account](https://docs.sparklayer.io/ignite/api/create-a-new-customer-sub-account.md)
- [PATCH Update a sub-account](https://docs.sparklayer.io/ignite/api/update-an-existing-customer-sub-account.md)
- [DELETE Delete a sub-account](https://docs.sparklayer.io/ignite/api/remove-a-customer-sub-account.md)
- [POST Create a customer address](https://docs.sparklayer.io/ignite/api/create-a-new-customer-address.md)
- [DELETE Delete a customer address](https://docs.sparklayer.io/ignite/api/remove-a-customer-address.md)
- [PUT Update a customer address](https://docs.sparklayer.io/ignite/api/update-a-customer-address.md)
- [POST Calculate tax and shipping](https://docs.sparklayer.io/ignite/api/calculate-tax-and-shipping.md)
- [POST Complete checkout](https://docs.sparklayer.io/ignite/api/complete-checkout.md)
- [GET List entities for a sync](https://docs.sparklayer.io/ignite/api/list-entities.md)
- [POST Fetch an entity](https://docs.sparklayer.io/ignite/api/fetch-entity.md)
- [POST Trigger a data sync](https://docs.sparklayer.io/ignite/api/trigger-a-data-sync.md)
- [GET Get metafield configuration](https://docs.sparklayer.io/ignite/api/get-metafield-configuration.md)
- [POST Enable a metafield](https://docs.sparklayer.io/ignite/api/enable-a-metafield.md)
- [POST Verify storefront authentication](https://docs.sparklayer.io/ignite/api/verify-authentication.md)

## Next steps

- [Endpoints overview](https://docs.sparklayer.io/ignite/endpoints-overview.md): what each endpoint is for.
- [Platform connection](https://docs.sparklayer.io/ignite/platform-connection.md): the first endpoints SparkLayer calls.


---

# Connect a platform

URL: https://docs.sparklayer.io/ignite/api/new-platform-connection
Operation: `POST /v1/{siteEnv}/{siteId}` (operationId `createPlatformConnection`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

The SparkLayer Ignite platform will call this endpoint when the merchant connects SparkLayer on the specific platform. Please note that this endpoint must be idempotent as it may be called multiple times.

`POST /v1/{siteEnv}/{siteId}`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
POST /v1/live/bobs-store HTTP/1.1
Host: ignite.example.com
Content-Type: application/json

{
  "store_id": "1234",
  "spark_api_client_id": "ca7cf4ac-51cb-4836-9a79-d425afc6e280",
  "spark_api_client_secret": "puwUwJZRfsnpB7nENulMW67prs94QYbu2DXHL3Sh",
  "extra_config": {
    "woocommerce_api_key": "<woocommerce_api_key>",
    "woocommerce_api_secret": "<woocommerce_api_secret>",
    "woocommerce_basic_user": "<woocommerce_basic_user>",
    "woocommerce_basic_pass": "<woocommerce_basic_pass>"
  },
  "magento_consumer_key": "<magento_consumer_key>",
  "magento_consumer_secret": "<magento_consumer_secret>",
  "magento_access_token": "<magento_access_token>",
  "magento_access_token_secret": "<magento_access_token_secret>"
}
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `store_id` | string | Yes | The ID of the store on the 3rd party platform |
| `spark_api_client_id` | string | Yes | |
| `spark_api_client_secret` | string | Yes | |
| `extra_config` | object \| null | | WooCommerce only. The credentials SparkLayer uses to call the merchant's WooCommerce REST API. |
| `extra_config.woocommerce_api_key` | string \| null | | |
| `extra_config.woocommerce_api_secret` | string \| null | | |
| `extra_config.woocommerce_basic_user` | string \| null | | |
| `extra_config.woocommerce_basic_pass` | string \| null | | |
| `magento_consumer_key` | string \| null | | Magento only |
| `magento_consumer_secret` | string \| null | | Magento only |
| `magento_access_token` | string \| null | | Magento only |
| `magento_access_token_secret` | string \| null | | Magento only |

```json
{
  "store_id": "1234",
  "spark_api_client_id": "ca7cf4ac-51cb-4836-9a79-d425afc6e280",
  "spark_api_client_secret": "puwUwJZRfsnpB7nENulMW67prs94QYbu2DXHL3Sh",
  "extra_config": {
    "woocommerce_api_key": "<woocommerce_api_key>",
    "woocommerce_api_secret": "<woocommerce_api_secret>",
    "woocommerce_basic_user": "<woocommerce_basic_user>",
    "woocommerce_basic_pass": "<woocommerce_basic_pass>"
  },
  "magento_consumer_key": "<magento_consumer_key>",
  "magento_consumer_secret": "<magento_consumer_secret>",
  "magento_access_token": "<magento_access_token>",
  "magento_access_token_secret": "<magento_access_token_secret>"
}
```

### Responses your service returns

#### 201: Successful operation - App install pending

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `redirect_url` | string | Yes | Platform store app install URL to redirect the merchant to in order to complete the connection |

```json
{
  "redirect_url": "https://store-1234.example.io/install"
}
```

#### 204: Successful operation - App already installed - Platform connection is now active

#### 401: Auth Failure

#### 500: System Exception


---

# Disconnect a platform

URL: https://docs.sparklayer.io/ignite/api/remove-platform-connection
Operation: `DELETE /v1/{siteEnv}/{siteId}` (operationId `removePlatformConnection`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

SparkLayer Ignite platform will call this endpoint when the merchant disconnects SparkLayer on the specific platform.

`DELETE /v1/{siteEnv}/{siteId}`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
DELETE /v1/live/bobs-store HTTP/1.1
Host: ignite.example.com
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |

### Responses your service returns

#### 204: Successful operation

#### 401: Auth Failure

#### 500: System Exception


---

# Create or update a customer

URL: https://docs.sparklayer.io/ignite/api/create-update-a-customer
Operation: `PUT /v1/{siteEnv}/{siteId}/customers` (operationId `createUpdateCustomer`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

Create or update a "customer" on the eCommerce platform.
The email address of the customer should be used as the unique identifier for finding the customer on the target platform.

`PUT /v1/{siteEnv}/{siteId}/customers`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
PUT /v1/live/bobs-store/customers HTTP/1.1
Host: ignite.example.com
Content-Type: application/json

{
  "email": "bob@sparklayer.io",
  "first_name": "Bob",
  "last_name": "Jones",
  "company_name": "Tom Jones Climbing Ltd",
  "accounting_id": "<accounting_id>",
  "sales_agent_groups": [
    "group-1"
  ],
  "price_lists": [
    "25-off"
  ],
  "customer_discount_percentage": 25,
  "group": "50-off",
  "role": "limited-customer",
  "addresses": [
    {
      "title": "Mr",
      "first_name": "Bob",
      "last_name": "Jones",
      "company": "Tom Jones Climbing Ltd",
      "address_line1": "Example Industrial Estate",
      "address_line2": "North Country",
      "city": "Cityland",
      "region_name": "California",
      "region_code": "CA",
      "postal_code": "12345",
      "country_code": "US",
      "phone": "+44 (0) 123456789",
      "is_default_shipping": true,
      "is_default_billing": true,
      "is_temporary": true
    }
  ],
  "send_invite": true,
  "tax_exempt": true,
  "parent_customer_external_id": "CU1234",
  "additional_tags": [
    "high-priority"
  ],
  "payment_on_account": {
    "credit_limit": 0,
    "balance": 0,
    "currency_code": "<currency_code>",
    "net_terms": "7_days"
  }
}
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | Yes | |
| `first_name` | string | Yes | Length: min 1, max 128. |
| `last_name` | string | Yes | Length: min 1, max 128. |
| `company_name` | string \| null | | Length: max 128. |
| `accounting_id` | string \| null | | The identifier for the customer in the merchant's accountancy or ERP. Length: min 1, max 124. |
| `sales_agent_groups` | string[] \| null | | |
| `price_lists` | string[] \| null | | |
| `customer_discount_percentage` | number (float) \| null | | |
| `group` | string \| null | | Length: max 128. |
| `role` | string \| null | | |
| `addresses` | object[] \| null | | List of customer addresses |
| `addresses[].title` | string \| null | | Length: max 30. |
| `addresses[].first_name` | string \| null | | Length: max 50. |
| `addresses[].last_name` | string \| null | | Length: max 50. |
| `addresses[].company` | string \| null | | Length: max 128. |
| `addresses[].address_line1` | string | | Length: max 255. |
| `addresses[].address_line2` | string \| null | | Length: max 255. |
| `addresses[].city` | string | | Length: max 128. |
| `addresses[].region_name` | string \| null | | Length: max 128. |
| `addresses[].region_code` | string \| null | | Length: max 10. |
| `addresses[].postal_code` | string \| null | | Length: max 20. |
| `addresses[].country_code` | string | | Two letter country code as defined by ISO 3166-2. Length: max 2. |
| `addresses[].phone` | string | | Length: max 20. |
| `addresses[].is_default_shipping` | boolean | | |
| `addresses[].is_default_billing` | boolean | | |
| `addresses[].is_temporary` | boolean | | Whether the address is temporary for the duration of a cart. This value is only relevant to platforms that create the order address automatically on order creation (or conversion from draft to normal order as in the case of our Shopify integration). In such cases we will want the integration to ensure this address does not get created in SparkLayer when the platform notifes the integration of a new customer address. |
| `send_invite` | boolean \| null | | |
| `tax_exempt` | boolean | | Whether the customer is tax exempt or not. This is only relevant to platforms that support tax exemption. |
| `parent_customer_external_id` | string \| null | | Parent Customer ID of the Customer |
| `additional_tags` | string[] \| null | | Additional tags to appear on the customer in Shopify. Automatically prefixed with spark- |
| `payment_on_account` | object \| null | | |
| `payment_on_account.credit_limit` | number (float) \| null | | Max 999999999.999. |
| `payment_on_account.balance` | number (float) \| null | | Max 999999999.999. |
| `payment_on_account.currency_code` | string \| null | | If set allows overriding the currency for the customer, otherwise the base currency of the store is to be used. Pattern: `^[A-Za-z]{3}$`. |
| `payment_on_account.net_terms` | "7_days" \| "15_days" \| "30_days" \| "45_days" \| "60_days" \| "90_days" \| null | | |

```json
{
  "email": "bob@sparklayer.io",
  "first_name": "Bob",
  "last_name": "Jones",
  "company_name": "Tom Jones Climbing Ltd",
  "accounting_id": "<accounting_id>",
  "sales_agent_groups": [
    "group-1"
  ],
  "price_lists": [
    "25-off"
  ],
  "customer_discount_percentage": 25,
  "group": "50-off",
  "role": "limited-customer",
  "addresses": [
    {
      "title": "Mr",
      "first_name": "Bob",
      "last_name": "Jones",
      "company": "Tom Jones Climbing Ltd",
      "address_line1": "Example Industrial Estate",
      "address_line2": "North Country",
      "city": "Cityland",
      "region_name": "California",
      "region_code": "CA",
      "postal_code": "12345",
      "country_code": "US",
      "phone": "+44 (0) 123456789",
      "is_default_shipping": true,
      "is_default_billing": true,
      "is_temporary": true
    }
  ],
  "send_invite": true,
  "tax_exempt": true,
  "parent_customer_external_id": "CU1234",
  "additional_tags": [
    "high-priority"
  ],
  "payment_on_account": {
    "credit_limit": 0,
    "balance": 0,
    "currency_code": "<currency_code>",
    "net_terms": "7_days"
  }
}
```

### Responses your service returns

#### 201: Successful operation

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `customer_external_id` | string | | Platform ID of Customer |

```json
{
  "customer_external_id": "CU1234"
}
```

#### 401: Auth Failure

#### 500: System Exception


---

# Create a sub-account

URL: https://docs.sparklayer.io/ignite/api/create-a-new-customer-sub-account
Operation: `POST /v1/{siteEnv}/{siteId}/sub-accounts` (operationId `createSubAccount`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

Create a new "customer" on the eCommerce platform and designates it as a sub-account with `parent_customer_id` as an attribute.
The implementation should explicitly handle the possibility that a customer with the supplied email address already exists and return a 400 response as documented.
If the target platform has the ability to send an activation / invitation email to the new customer then this should be done.

`POST /v1/{siteEnv}/{siteId}/sub-accounts`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
POST /v1/live/bobs-store/sub-accounts HTTP/1.1
Host: ignite.example.com
Content-Type: application/json

{
  "email": "bob@sparklayer.io",
  "first_name": "Bob",
  "last_name": "Jones",
  "parent_customer_external_id": "CU1234",
  "role": "limited-customer"
}
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | Yes | |
| `first_name` | string | Yes | Length: min 1, max 128. |
| `last_name` | string | Yes | Length: min 1, max 128. |
| `parent_customer_external_id` | string | Yes | Parent Customer ID of the Customer |
| `role` | string \| null | | A role that represents the users permissions |

```json
{
  "email": "bob@sparklayer.io",
  "first_name": "Bob",
  "last_name": "Jones",
  "parent_customer_external_id": "CU1234",
  "role": "limited-customer"
}
```

### Responses your service returns

#### 201: Successful operation

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `customer_external_id` | string | | Platform ID of Customer |

```json
{
  "customer_external_id": "CU1234"
}
```

#### 400: Error handling request such as email already taken

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error_code` | "email-already-taken" | | Machine-readable error code such as email already taken |

```json
{
  "error_code": "email-already-taken"
}
```

#### 401: Auth Failure

#### 500: System Exception


---

# Delete a sub-account

URL: https://docs.sparklayer.io/ignite/api/remove-a-customer-sub-account
Operation: `DELETE /v1/{siteEnv}/{siteId}/sub-accounts/{customer_external_id}` (operationId `deleteSubAccount`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

Remove a customer sub-account from the specific platform, ensuring the account can no longer interact with the parent account.
Platforms may prevent the deletion of customers which have orders, for this reason it is recommended that the `parent_customer_external_id` attribute is removed from the customer object rather than actual deletion.

`DELETE /v1/{siteEnv}/{siteId}/sub-accounts/{customer_external_id}`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
DELETE /v1/live/bobs-store/sub-accounts/CUS1234 HTTP/1.1
Host: ignite.example.com
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |
| `customer_external_id` | string | Yes | The customer's ID on your platform. Length: min 1. Example: `CUS1234` |

### Responses your service returns

#### 204: Successful operation

#### 401: Auth Failure

#### 404: Customer not found

#### 500: System Exception


---

# Update a sub-account

URL: https://docs.sparklayer.io/ignite/api/update-an-existing-customer-sub-account
Operation: `PATCH /v1/{siteEnv}/{siteId}/sub-accounts/{customer_external_id}` (operationId `updateSubAccount`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

Update the details of an existing customer sub-account. This allows changing the account's first name, last name and role.
This does not allow for the email to be updated.

`PATCH /v1/{siteEnv}/{siteId}/sub-accounts/{customer_external_id}`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
PATCH /v1/live/bobs-store/sub-accounts/CUS1234 HTTP/1.1
Host: ignite.example.com
Content-Type: application/json

{
  "first_name": "Bob",
  "last_name": "Jones",
  "role": "limited-customer"
}
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |
| `customer_external_id` | string | Yes | The customer's ID on your platform. Length: min 1. Example: `CUS1234` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `first_name` | string | | Length: min 1, max 128. |
| `last_name` | string | | Length: min 1, max 128. |
| `role` | string \| null | | A role that represents the users permissions |

```json
{
  "first_name": "Bob",
  "last_name": "Jones",
  "role": "limited-customer"
}
```

### Responses your service returns

#### 201: Successful operation

#### 400: Error handling request such as name too short

#### 401: Auth Failure

#### 500: System Exception


---

# Create a customer address

URL: https://docs.sparklayer.io/ignite/api/create-a-new-customer-address
Operation: `POST /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses` (operationId `createCustomerAddress`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

Create a new "address" for a customer on the specific platform.

`POST /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
POST /v1/live/bobs-store/customers/CUS1234/addresses HTTP/1.1
Host: ignite.example.com
Content-Type: application/json

{
  "title": "Mr",
  "first_name": "Bob",
  "last_name": "Jones",
  "company": "Tom Jones Climbing Ltd",
  "address_line1": "Example Industrial Estate",
  "address_line2": "North Country",
  "city": "Cityland",
  "region_name": "California",
  "region_code": "CA",
  "postal_code": "12345",
  "country_code": "US",
  "phone": "+44 (0) 123456789",
  "is_default_shipping": true,
  "is_default_billing": true,
  "is_temporary": true
}
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |
| `customer_external_id` | string | Yes | The customer's ID on your platform. Length: min 1. Example: `CUS1234` |

### Request body (`application/json`) (required)

Address.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string \| null | | Length: max 30. |
| `first_name` | string \| null | | Length: max 50. |
| `last_name` | string \| null | | Length: max 50. |
| `company` | string \| null | | Length: max 128. |
| `address_line1` | string | | Length: max 255. |
| `address_line2` | string \| null | | Length: max 255. |
| `city` | string | | Length: max 128. |
| `region_name` | string \| null | | Length: max 128. |
| `region_code` | string \| null | | Length: max 10. |
| `postal_code` | string \| null | | Length: max 20. |
| `country_code` | string | | Two letter country code as defined by ISO 3166-2. Length: max 2. |
| `phone` | string | | Length: max 20. |
| `is_default_shipping` | boolean | | |
| `is_default_billing` | boolean | | |
| `is_temporary` | boolean | | Whether the address is temporary for the duration of a cart. This value is only relevant to platforms that create the order address automatically on order creation (or conversion from draft to normal order as in the case of our Shopify integration). In such cases we will want the integration to ensure this address does not get created in SparkLayer when the platform notifes the integration of a new customer address. |

```json
{
  "title": "Mr",
  "first_name": "Bob",
  "last_name": "Jones",
  "company": "Tom Jones Climbing Ltd",
  "address_line1": "Example Industrial Estate",
  "address_line2": "North Country",
  "city": "Cityland",
  "region_name": "California",
  "region_code": "CA",
  "postal_code": "12345",
  "country_code": "US",
  "phone": "+44 (0) 123456789",
  "is_default_shipping": true,
  "is_default_billing": true,
  "is_temporary": true
}
```

### Responses your service returns

#### 201: Successful Address

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string \| null | | Length: max 30. |
| `first_name` | string \| null | | Length: max 50. |
| `last_name` | string \| null | | Length: max 50. |
| `company` | string \| null | | Length: max 128. |
| `address_line1` | string | | Length: max 255. |
| `address_line2` | string \| null | | Length: max 255. |
| `city` | string | | Length: max 128. |
| `region_name` | string \| null | | Length: max 128. |
| `region_code` | string \| null | | Length: max 10. |
| `postal_code` | string \| null | | Length: max 20. |
| `country_code` | string | | Two letter country code as defined by ISO 3166-2. Length: max 2. |
| `phone` | string | | Length: max 20. |
| `is_default_shipping` | boolean | | |
| `is_default_billing` | boolean | | |
| `customer_address_external_id` | string | | eCommerce platform ID for the Customer Address. Length: max 50. |

```json
{
  "title": "Mr",
  "first_name": "Bob",
  "last_name": "Jones",
  "company": "Tom Jones Climbing Ltd",
  "address_line1": "Example Industrial Estate",
  "address_line2": "North Country",
  "city": "Cityland",
  "region_name": "California",
  "region_code": "CA",
  "postal_code": "12345",
  "country_code": "US",
  "phone": "+44 (0) 123456789",
  "is_default_shipping": true,
  "is_default_billing": true,
  "customer_address_external_id": "<customer_address_external_id>"
}
```

#### 401: Auth Failure

#### 500: System Exception


---

# Update a customer address

URL: https://docs.sparklayer.io/ignite/api/update-a-customer-address
Operation: `PUT /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses/{customer_address_external_id}` (operationId `updateCustomerAddress`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

Update a customer address on the specific platform.

`PUT /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses/{customer_address_external_id}`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
PUT /v1/live/bobs-store/customers/CUS1234/addresses/ADD1234567 HTTP/1.1
Host: ignite.example.com
Content-Type: application/json

{
  "title": "Mr",
  "first_name": "Bob",
  "last_name": "Jones",
  "company": "Tom Jones Climbing Ltd",
  "address_line1": "Example Industrial Estate",
  "address_line2": "North Country",
  "city": "Cityland",
  "region_name": "California",
  "region_code": "CA",
  "postal_code": "12345",
  "country_code": "US",
  "phone": "+44 (0) 123456789",
  "is_default_shipping": true,
  "is_default_billing": true,
  "is_temporary": true
}
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |
| `customer_external_id` | string | Yes | The customer's ID on your platform. Length: min 1. Example: `CUS1234` |
| `customer_address_external_id` | string | Yes | The address's ID on your platform. Length: min 1. Example: `ADD1234567` |

### Request body (`application/json`) (required)

Address.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string \| null | | Length: max 30. |
| `first_name` | string \| null | | Length: max 50. |
| `last_name` | string \| null | | Length: max 50. |
| `company` | string \| null | | Length: max 128. |
| `address_line1` | string | | Length: max 255. |
| `address_line2` | string \| null | | Length: max 255. |
| `city` | string | | Length: max 128. |
| `region_name` | string \| null | | Length: max 128. |
| `region_code` | string \| null | | Length: max 10. |
| `postal_code` | string \| null | | Length: max 20. |
| `country_code` | string | | Two letter country code as defined by ISO 3166-2. Length: max 2. |
| `phone` | string | | Length: max 20. |
| `is_default_shipping` | boolean | | |
| `is_default_billing` | boolean | | |
| `is_temporary` | boolean | | Whether the address is temporary for the duration of a cart. This value is only relevant to platforms that create the order address automatically on order creation (or conversion from draft to normal order as in the case of our Shopify integration). In such cases we will want the integration to ensure this address does not get created in SparkLayer when the platform notifes the integration of a new customer address. |

```json
{
  "title": "Mr",
  "first_name": "Bob",
  "last_name": "Jones",
  "company": "Tom Jones Climbing Ltd",
  "address_line1": "Example Industrial Estate",
  "address_line2": "North Country",
  "city": "Cityland",
  "region_name": "California",
  "region_code": "CA",
  "postal_code": "12345",
  "country_code": "US",
  "phone": "+44 (0) 123456789",
  "is_default_shipping": true,
  "is_default_billing": true,
  "is_temporary": true
}
```

### Responses your service returns

#### 200: Successful Address

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string \| null | | Length: max 30. |
| `first_name` | string \| null | | Length: max 50. |
| `last_name` | string \| null | | Length: max 50. |
| `company` | string \| null | | Length: max 128. |
| `address_line1` | string | | Length: max 255. |
| `address_line2` | string \| null | | Length: max 255. |
| `city` | string | | Length: max 128. |
| `region_name` | string \| null | | Length: max 128. |
| `region_code` | string \| null | | Length: max 10. |
| `postal_code` | string \| null | | Length: max 20. |
| `country_code` | string | | Two letter country code as defined by ISO 3166-2. Length: max 2. |
| `phone` | string | | Length: max 20. |
| `is_default_shipping` | boolean | | |
| `is_default_billing` | boolean | | |
| `customer_address_external_id` | string | | eCommerce platform ID for the Customer Address. Length: max 50. |

```json
{
  "title": "Mr",
  "first_name": "Bob",
  "last_name": "Jones",
  "company": "Tom Jones Climbing Ltd",
  "address_line1": "Example Industrial Estate",
  "address_line2": "North Country",
  "city": "Cityland",
  "region_name": "California",
  "region_code": "CA",
  "postal_code": "12345",
  "country_code": "US",
  "phone": "+44 (0) 123456789",
  "is_default_shipping": true,
  "is_default_billing": true,
  "customer_address_external_id": "<customer_address_external_id>"
}
```

#### 401: Auth Failure

#### 500: System Exception


---

# Delete a customer address

URL: https://docs.sparklayer.io/ignite/api/remove-a-customer-address
Operation: `DELETE /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses/{customer_address_external_id}` (operationId `deleteCustomerAddress`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

Remove a customer address from the specific platform.

`DELETE /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses/{customer_address_external_id}`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
DELETE /v1/live/bobs-store/customers/CUS1234/addresses/ADD1234567 HTTP/1.1
Host: ignite.example.com
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |
| `customer_external_id` | string | Yes | The customer's ID on your platform. Length: min 1. Example: `CUS1234` |
| `customer_address_external_id` | string | Yes | The address's ID on your platform. Length: min 1. Example: `ADD1234567` |

### Responses your service returns

#### 204: Successful operation

#### 401: Auth Failure

#### 404: Not Found

#### 409: Conflict

#### 500: System Exception


---

# Calculate tax and shipping

URL: https://docs.sparklayer.io/ignite/api/calculate-tax-and-shipping
Operation: `POST /v1/{siteEnv}/{siteId}/checkout/calculate` (operationId `calculateOrder`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

This endpoint is called at the final step of the checkout process in order to show tax and shipping methods available to the customer.

`POST /v1/{siteEnv}/{siteId}/checkout/calculate`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
POST /v1/live/bobs-store/checkout/calculate HTTP/1.1
Host: ignite.example.com
Content-Type: application/json

{
  "cart_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
  "customer": {
    "id": "cu_1",
    "email": "buyer@example.com",
    "external_id": "CUS1234",
    "accounting_id": "<accounting_id>",
    "default_billing_address_id": "<default_billing_address_id>",
    "default_shipping_address_id": "<default_shipping_address_id>",
    "temporary_external_address_ids": [
      "<temporary_external_address_ids>"
    ],
    "payment_on_account": {
      "credit_limit": 0,
      "balance": 0,
      "currency_code": "<currency_code>",
      "net_terms": "7_days"
    }
  },
  "currency_code": "gbp",
  "billing_address": {
    "title": "Mr",
    "first_name": "Bob",
    "last_name": "Jones",
    "company": "Tom Jones Climbing Ltd",
    "address_line1": "Example Industrial Estate",
    "address_line2": "North Country",
    "city": "Cityland",
    "region_name": "California",
    "region_code": "CA",
    "postal_code": "12345",
    "country_code": "US",
    "phone": "+44 (0) 123456789",
    "is_default_shipping": true,
    "is_default_billing": true,
    "is_temporary": true
  },
  "shipping_address": {
    "title": "Mr",
    "first_name": "Bob",
    "last_name": "Jones",
    "company": "Tom Jones Climbing Ltd",
    "address_line1": "Example Industrial Estate",
    "address_line2": "North Country",
    "city": "Cityland",
    "region_name": "California",
    "region_code": "CA",
    "postal_code": "12345",
    "country_code": "US",
    "phone": "+44 (0) 123456789",
    "is_default_shipping": true,
    "is_default_billing": true,
    "is_temporary": true
  },
  "shipping_line": {
    "type": "platform",
    "id": "<id>",
    "name": "<name>",
    "price": 4.8,
    "tax_rate": 0.2
  },
  "internal_shipping_methods": [
    {
      "title": "<title>",
      "price_v2": {
        "tax_rate": 0,
        "net": 0,
        "gross": 0,
        "currency_code": "<currency_code>"
      },
      "handle": "<handle>",
      "cost_type": "<cost_type>",
      "cost_language_string": "<cost_language_string>"
    }
  ],
  "shop": {
    "base_currency_code": "gbp"
  },
  "line_items": [
    {
      "type": "product",
      "spark_item_key": "00a0c91e6bf600a0c91e6bf",
      "spark_variant_id": "8ac52999-d163-4d68-ae30-a5f0c089ed79",
      "sku": "EXAMPLE-SKU",
      "product_variant_external_id": "PROD123456",
      "product_external_id": "PROD1234",
      "quantity": 10,
      "unit_price": 4.8,
      "custom_attributes": [
        {
          "key": "<key>",
          "value": "<value>"
        }
      ],
      "options": [
        {
          "group": "<group>",
          "value": "<value>"
        }
      ]
    }
  ],
  "ignite_state": {},
  "ignite_checkout_context": {
    "channel_id": 12345
  },
  "shipping_method_source": "sparklayer"
}
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |

### Request body (`application/json`) (required)

Checkout.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `cart_id` | string (uuid) | | SparkLayer Cart ID |
| `customer` | object | | |
| `customer.id` | string | Yes | SparkLayer ID of Customer |
| `customer.email` | string (email) | Yes | |
| `customer.external_id` | string | Yes | eCommerce platform ID of Customer |
| `customer.accounting_id` | string \| null | | |
| `customer.default_billing_address_id` | string \| null | | eCommerce platform ID of default billing address |
| `customer.default_shipping_address_id` | string \| null | | eCommerce platform ID of default shipping address |
| `customer.temporary_external_address_ids` | string[] | | List of temporary (drop shipping) address IDs associated with the customer to be deleted once the order has been completed. Should be the external (platform) address ID |
| `customer.payment_on_account` | object \| null | | |
| `customer.payment_on_account.credit_limit` | number (float) \| null | | Max 999999999.999. |
| `customer.payment_on_account.balance` | number (float) \| null | | Max 999999999.999. |
| `customer.payment_on_account.currency_code` | string \| null | | If set allows overriding the currency for the customer, otherwise the base currency of the store is to be used. Pattern: `^[A-Za-z]{3}$`. |
| `customer.payment_on_account.net_terms` | "7_days" \| "15_days" \| "30_days" \| "45_days" \| "60_days" \| "90_days" \| null | | |
| `currency_code` | string | | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. Length: min 3, max 3. |
| `billing_address` | object | | |
| `billing_address.title` | string \| null | | Length: max 30. |
| `billing_address.first_name` | string \| null | | Length: max 50. |
| `billing_address.last_name` | string \| null | | Length: max 50. |
| `billing_address.company` | string \| null | | Length: max 128. |
| `billing_address.address_line1` | string | | Length: max 255. |
| `billing_address.address_line2` | string \| null | | Length: max 255. |
| `billing_address.city` | string | | Length: max 128. |
| `billing_address.region_name` | string \| null | | Length: max 128. |
| `billing_address.region_code` | string \| null | | Length: max 10. |
| `billing_address.postal_code` | string \| null | | Length: max 20. |
| `billing_address.country_code` | string | | Two letter country code as defined by ISO 3166-2. Length: max 2. |
| `billing_address.phone` | string | | Length: max 20. |
| `billing_address.is_default_shipping` | boolean | | |
| `billing_address.is_default_billing` | boolean | | |
| `billing_address.is_temporary` | boolean | | Whether the address is temporary for the duration of a cart. This value is only relevant to platforms that create the order address automatically on order creation (or conversion from draft to normal order as in the case of our Shopify integration). In such cases we will want the integration to ensure this address does not get created in SparkLayer when the platform notifes the integration of a new customer address. |
| `shipping_address` | object | | |
| `shipping_address.title` | string \| null | | Length: max 30. |
| `shipping_address.first_name` | string \| null | | Length: max 50. |
| `shipping_address.last_name` | string \| null | | Length: max 50. |
| `shipping_address.company` | string \| null | | Length: max 128. |
| `shipping_address.address_line1` | string | | Length: max 255. |
| `shipping_address.address_line2` | string \| null | | Length: max 255. |
| `shipping_address.city` | string | | Length: max 128. |
| `shipping_address.region_name` | string \| null | | Length: max 128. |
| `shipping_address.region_code` | string \| null | | Length: max 10. |
| `shipping_address.postal_code` | string \| null | | Length: max 20. |
| `shipping_address.country_code` | string | | Two letter country code as defined by ISO 3166-2. Length: max 2. |
| `shipping_address.phone` | string | | Length: max 20. |
| `shipping_address.is_default_shipping` | boolean | | |
| `shipping_address.is_default_billing` | boolean | | |
| `shipping_address.is_temporary` | boolean | | Whether the address is temporary for the duration of a cart. This value is only relevant to platforms that create the order address automatically on order creation (or conversion from draft to normal order as in the case of our Shopify integration). In such cases we will want the integration to ensure this address does not get created in SparkLayer when the platform notifes the integration of a new customer address. |
| `shipping_line` | ShippingLine \| ShippingLinePlatformIdOnly \| null | | If using platform shipping, on the first load of the final checkout screen, this will be `null`, after it will be an ID from a method from the response of `available_shipping_methods` If using SparkLayer shipping, this can be `null` if none found or will be the method. |
| `internal_shipping_methods` | object[] \| null | | **Deprecated.** List of available SparkLayer shipping methods for the given checkout, if not using spark shipping this will be empty. |
| `internal_shipping_methods[].title` | string | | |
| `internal_shipping_methods[].price_v2` | object | | |
| `internal_shipping_methods[].price_v2.tax_rate` | number | | |
| `internal_shipping_methods[].price_v2.net` | number | | |
| `internal_shipping_methods[].price_v2.gross` | number | | |
| `internal_shipping_methods[].price_v2.currency_code` | string | | |
| `internal_shipping_methods[].handle` | string | | |
| `internal_shipping_methods[].cost_type` | string | | |
| `internal_shipping_methods[].cost_language_string` | string \| null | | |
| `shop` | object | | |
| `shop.base_currency_code` | string | | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. Length: min 3, max 3. |
| `line_items` | (LineItemProduct \| LineItemCustom)[] | | |
| `line_items[].type` | "product" | | |
| `line_items[].spark_item_key` | string | | Length: max 32. |
| `line_items[].spark_variant_id` | string | | Length: max 36. |
| `line_items[].sku` | string | | |
| `line_items[].product_variant_external_id` | string | | eCommerce platform ID of Product Variant |
| `line_items[].product_external_id` | string | | eCommerce platform ID of Product |
| `line_items[].quantity` | integer | | |
| `line_items[].unit_price` | number | | Net price of a unit |
| `line_items[].custom_attributes` | object[] | | Custom attributes allow arbitrary data to be attached to a line item |
| `line_items[].custom_attributes[].key` | string | | |
| `line_items[].custom_attributes[].value` | string | | |
| `line_items[].options` | object[] \| null | | |
| `line_items[].options[].group` | string | | |
| `line_items[].options[].value` | string | | |
| `line_items[].name` | string | | Length: max 128. |
| `ignite_state` | object | | Context which was set by a previous response from /checkout/calculate |
| `ignite_checkout_context` | object \| null | | Extra context provided by the checkout frontend. This allows passing arbitrary platform-specific data that might be needed by the platform's checkout process. For example, for BigCommerce, this could be used to pass a `channel_id` from the store theme to the ignite integration in order to support multi-channel stores. |
| `shipping_method_source` | "sparklayer" \| "platform" | | Specifies the store's configured source for retrieving shipping methods during checkout. When `sparklayer`, a `null` `shipping_line` means the cart has no shipping charge, and no platform rate is fetched or applied. Absent is treated as `platform`. |

```json
{
  "cart_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
  "customer": {
    "id": "cu_1",
    "email": "buyer@example.com",
    "external_id": "CUS1234",
    "accounting_id": "<accounting_id>",
    "default_billing_address_id": "<default_billing_address_id>",
    "default_shipping_address_id": "<default_shipping_address_id>",
    "temporary_external_address_ids": [
      "<temporary_external_address_ids>"
    ],
    "payment_on_account": {
      "credit_limit": 0,
      "balance": 0,
      "currency_code": "<currency_code>",
      "net_terms": "7_days"
    }
  },
  "currency_code": "gbp",
  "billing_address": {
    "title": "Mr",
    "first_name": "Bob",
    "last_name": "Jones",
    "company": "Tom Jones Climbing Ltd",
    "address_line1": "Example Industrial Estate",
    "address_line2": "North Country",
    "city": "Cityland",
    "region_name": "California",
    "region_code": "CA",
    "postal_code": "12345",
    "country_code": "US",
    "phone": "+44 (0) 123456789",
    "is_default_shipping": true,
    "is_default_billing": true,
    "is_temporary": true
  },
  "shipping_address": {
    "title": "Mr",
    "first_name": "Bob",
    "last_name": "Jones",
    "company": "Tom Jones Climbing Ltd",
    "address_line1": "Example Industrial Estate",
    "address_line2": "North Country",
    "city": "Cityland",
    "region_name": "California",
    "region_code": "CA",
    "postal_code": "12345",
    "country_code": "US",
    "phone": "+44 (0) 123456789",
    "is_default_shipping": true,
    "is_default_billing": true,
    "is_temporary": true
  },
  "shipping_line": {
    "type": "platform",
    "id": "<id>",
    "name": "<name>",
    "price": 4.8,
    "tax_rate": 0.2
  },
  "internal_shipping_methods": [
    {
      "title": "<title>",
      "price_v2": {
        "tax_rate": 0,
        "net": 0,
        "gross": 0,
        "currency_code": "<currency_code>"
      },
      "handle": "<handle>",
      "cost_type": "<cost_type>",
      "cost_language_string": "<cost_language_string>"
    }
  ],
  "shop": {
    "base_currency_code": "gbp"
  },
  "line_items": [
    {
      "type": "product",
      "spark_item_key": "00a0c91e6bf600a0c91e6bf",
      "spark_variant_id": "8ac52999-d163-4d68-ae30-a5f0c089ed79",
      "sku": "EXAMPLE-SKU",
      "product_variant_external_id": "PROD123456",
      "product_external_id": "PROD1234",
      "quantity": 10,
      "unit_price": 4.8,
      "custom_attributes": [
        {
          "key": "<key>",
          "value": "<value>"
        }
      ],
      "options": [
        {
          "group": "<group>",
          "value": "<value>"
        }
      ]
    }
  ],
  "ignite_state": {},
  "ignite_checkout_context": {
    "channel_id": 12345
  },
  "shipping_method_source": "sparklayer"
}
```

### Responses your service returns

#### 200: Returns tax and shipping information

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `available_shipping_methods` | object[] | | |
| `available_shipping_methods[].id` | string | | |
| `available_shipping_methods[].name` | string | | |
| `available_shipping_methods[].price` | number | | Net of tax |
| `available_shipping_methods[].currency_code` | string | | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. Length: min 3, max 3. |
| `platform_shipping_line` | object | | The shipping line applied to the order in the eCommerce platform. Determines price and tax amounts for SparkLayer. |
| `platform_shipping_line.type` | "platform" \| "sparklayer" | | |
| `platform_shipping_line.id` | string | | |
| `platform_shipping_line.name` | string | | |
| `platform_shipping_line.price` | number | | Net of tax |
| `platform_shipping_line.tax_rate` | number | | |
| `totals` | object | | |
| `totals.line_items` | number | | Sub-total of line items (Nett of tax) |
| `totals.shipping_price` | number | | Shipping cost (Nett of tax) |
| `totals.tax` | number | | Tax for the order |
| `totals.total_price` | number | | Order total (Gross of tax) |
| `ignite_state` | object | | Context which will be provided in subsequent requests to /checkout/complete |

```json
{
  "available_shipping_methods": [
    {
      "id": "next-day",
      "name": "Next day delivery",
      "price": 4.8,
      "currency_code": "gbp"
    }
  ],
  "platform_shipping_line": {
    "type": "platform",
    "id": "<id>",
    "name": "<name>",
    "price": 4.8,
    "tax_rate": 0.2
  },
  "totals": {
    "line_items": 14.8,
    "shipping_price": 4.8,
    "tax": 2.2,
    "total_price": 21.8
  },
  "ignite_state": {}
}
```

#### 400: Invalid state/configuration caused the request to fail

`application/problem+json`: the standard error body (below).

#### 401: Auth Failure

#### 500: System Exception

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable detail of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Human-readable summary of the error |
| `type` | string | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```


---

# Complete checkout

URL: https://docs.sparklayer.io/ignite/api/complete-checkout
Operation: `POST /v1/{siteEnv}/{siteId}/checkout/complete` (operationId `completeOrder`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

This endpoint is called at the final step once the customer attempts to complete the order. If the payment type is `upfrontPayment` the customer should be directed to the checkout flow to complete payment. Alternatively, an order can be created there and then for other systems to manage payments.

At this point, either redirect the user to a URL to complete the transaction or return a ID of the order being created on the platform.

`POST /v1/{siteEnv}/{siteId}/checkout/complete`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
POST /v1/live/bobs-store/checkout/complete HTTP/1.1
Host: ignite.example.com
Content-Type: application/json

{
  "cart_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
  "customer": {
    "id": "cu_1",
    "email": "buyer@example.com",
    "external_id": "CUS1234",
    "accounting_id": "<accounting_id>",
    "default_billing_address_id": "<default_billing_address_id>",
    "default_shipping_address_id": "<default_shipping_address_id>",
    "temporary_external_address_ids": [
      "<temporary_external_address_ids>"
    ],
    "payment_on_account": {
      "credit_limit": 0,
      "balance": 0,
      "currency_code": "<currency_code>",
      "net_terms": "7_days"
    }
  },
  "currency_code": "gbp",
  "billing_address": {
    "title": "Mr",
    "first_name": "Bob",
    "last_name": "Jones",
    "company": "Tom Jones Climbing Ltd",
    "address_line1": "Example Industrial Estate",
    "address_line2": "North Country",
    "city": "Cityland",
    "region_name": "California",
    "region_code": "CA",
    "postal_code": "12345",
    "country_code": "US",
    "phone": "+44 (0) 123456789",
    "is_default_shipping": true,
    "is_default_billing": true,
    "is_temporary": true
  },
  "shipping_address": {
    "title": "Mr",
    "first_name": "Bob",
    "last_name": "Jones",
    "company": "Tom Jones Climbing Ltd",
    "address_line1": "Example Industrial Estate",
    "address_line2": "North Country",
    "city": "Cityland",
    "region_name": "California",
    "region_code": "CA",
    "postal_code": "12345",
    "country_code": "US",
    "phone": "+44 (0) 123456789",
    "is_default_shipping": true,
    "is_default_billing": true,
    "is_temporary": true
  },
  "shipping_line": {
    "type": "platform",
    "id": "<id>",
    "name": "<name>",
    "price": 4.8,
    "tax_rate": 0.2
  },
  "internal_shipping_methods": [
    {
      "title": "<title>",
      "price_v2": {
        "tax_rate": 0,
        "net": 0,
        "gross": 0,
        "currency_code": "<currency_code>"
      },
      "handle": "<handle>",
      "cost_type": "<cost_type>",
      "cost_language_string": "<cost_language_string>"
    }
  ],
  "shop": {
    "base_currency_code": "gbp"
  },
  "line_items": [
    {
      "type": "product",
      "spark_item_key": "00a0c91e6bf600a0c91e6bf",
      "spark_variant_id": "8ac52999-d163-4d68-ae30-a5f0c089ed79",
      "sku": "EXAMPLE-SKU",
      "product_variant_external_id": "PROD123456",
      "product_external_id": "PROD1234",
      "quantity": 10,
      "unit_price": 4.8,
      "custom_attributes": [
        {
          "key": "<key>",
          "value": "<value>"
        }
      ],
      "options": [
        {
          "group": "<group>",
          "value": "<value>"
        }
      ]
    }
  ],
  "ignite_state": {},
  "ignite_checkout_context": {
    "channel_id": 12345
  },
  "shipping_method_source": "sparklayer",
  "payment_type": "upfrontPayment",
  "sales_agent": {
    "id": "cu_1",
    "email": "buyer@example.com",
    "accounting_id": "<accounting_id>"
  },
  "company_user": {
    "id": "cu_1",
    "email": "buyer@example.com",
    "external_id": "CUS1234",
    "accounting_id": "<accounting_id>"
  },
  "additional_info": "<additional_info>",
  "po_number": "PO-001",
  "shipping_requested_date": "2020-01-01T00:00:00+02:00",
  "custom_fields": {},
  "discount_data": {
    "sub_total_pre_discount": {
      "net": 0
    },
    "sub_total_discount": {
      "net": 0
    },
    "shipping_pre_discount": {
      "net": 0
    },
    "shipping_discount": {
      "net": 0
    },
    "line_item_discounts": [
      {
        "pre_discount": {
          "net": 0
        },
        "discount": {
          "net": 0
        },
        "sku": "<sku>",
        "item_key": "<item_key>"
      }
    ],
    "discount_slugs": [
      "<discount_slugs>"
    ]
  },
  "discount_coupon_codes": [
    "<discount_coupon_codes>"
  ]
}
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |

### Request body (`application/json`) (required)

Checkout.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `cart_id` | string (uuid) | | SparkLayer Cart ID |
| `customer` | object | | |
| `customer.id` | string | Yes | SparkLayer ID of Customer |
| `customer.email` | string (email) | Yes | |
| `customer.external_id` | string | Yes | eCommerce platform ID of Customer |
| `customer.accounting_id` | string \| null | | |
| `customer.default_billing_address_id` | string \| null | | eCommerce platform ID of default billing address |
| `customer.default_shipping_address_id` | string \| null | | eCommerce platform ID of default shipping address |
| `customer.temporary_external_address_ids` | string[] | | List of temporary (drop shipping) address IDs associated with the customer to be deleted once the order has been completed. Should be the external (platform) address ID |
| `customer.payment_on_account` | object \| null | | |
| `customer.payment_on_account.credit_limit` | number (float) \| null | | Max 999999999.999. |
| `customer.payment_on_account.balance` | number (float) \| null | | Max 999999999.999. |
| `customer.payment_on_account.currency_code` | string \| null | | If set allows overriding the currency for the customer, otherwise the base currency of the store is to be used. Pattern: `^[A-Za-z]{3}$`. |
| `customer.payment_on_account.net_terms` | "7_days" \| "15_days" \| "30_days" \| "45_days" \| "60_days" \| "90_days" \| null | | |
| `currency_code` | string | | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. Length: min 3, max 3. |
| `billing_address` | object | | |
| `billing_address.title` | string \| null | | Length: max 30. |
| `billing_address.first_name` | string \| null | | Length: max 50. |
| `billing_address.last_name` | string \| null | | Length: max 50. |
| `billing_address.company` | string \| null | | Length: max 128. |
| `billing_address.address_line1` | string | | Length: max 255. |
| `billing_address.address_line2` | string \| null | | Length: max 255. |
| `billing_address.city` | string | | Length: max 128. |
| `billing_address.region_name` | string \| null | | Length: max 128. |
| `billing_address.region_code` | string \| null | | Length: max 10. |
| `billing_address.postal_code` | string \| null | | Length: max 20. |
| `billing_address.country_code` | string | | Two letter country code as defined by ISO 3166-2. Length: max 2. |
| `billing_address.phone` | string | | Length: max 20. |
| `billing_address.is_default_shipping` | boolean | | |
| `billing_address.is_default_billing` | boolean | | |
| `billing_address.is_temporary` | boolean | | Whether the address is temporary for the duration of a cart. This value is only relevant to platforms that create the order address automatically on order creation (or conversion from draft to normal order as in the case of our Shopify integration). In such cases we will want the integration to ensure this address does not get created in SparkLayer when the platform notifes the integration of a new customer address. |
| `shipping_address` | object | | |
| `shipping_address.title` | string \| null | | Length: max 30. |
| `shipping_address.first_name` | string \| null | | Length: max 50. |
| `shipping_address.last_name` | string \| null | | Length: max 50. |
| `shipping_address.company` | string \| null | | Length: max 128. |
| `shipping_address.address_line1` | string | | Length: max 255. |
| `shipping_address.address_line2` | string \| null | | Length: max 255. |
| `shipping_address.city` | string | | Length: max 128. |
| `shipping_address.region_name` | string \| null | | Length: max 128. |
| `shipping_address.region_code` | string \| null | | Length: max 10. |
| `shipping_address.postal_code` | string \| null | | Length: max 20. |
| `shipping_address.country_code` | string | | Two letter country code as defined by ISO 3166-2. Length: max 2. |
| `shipping_address.phone` | string | | Length: max 20. |
| `shipping_address.is_default_shipping` | boolean | | |
| `shipping_address.is_default_billing` | boolean | | |
| `shipping_address.is_temporary` | boolean | | Whether the address is temporary for the duration of a cart. This value is only relevant to platforms that create the order address automatically on order creation (or conversion from draft to normal order as in the case of our Shopify integration). In such cases we will want the integration to ensure this address does not get created in SparkLayer when the platform notifes the integration of a new customer address. |
| `shipping_line` | ShippingLine \| ShippingLinePlatformIdOnly \| null | | If using platform shipping, on the first load of the final checkout screen, this will be `null`, after it will be an ID from a method from the response of `available_shipping_methods` If using SparkLayer shipping, this can be `null` if none found or will be the method. |
| `internal_shipping_methods` | object[] \| null | | **Deprecated.** List of available SparkLayer shipping methods for the given checkout, if not using spark shipping this will be empty. |
| `internal_shipping_methods[].title` | string | | |
| `internal_shipping_methods[].price_v2` | object | | |
| `internal_shipping_methods[].price_v2.tax_rate` | number | | |
| `internal_shipping_methods[].price_v2.net` | number | | |
| `internal_shipping_methods[].price_v2.gross` | number | | |
| `internal_shipping_methods[].price_v2.currency_code` | string | | |
| `internal_shipping_methods[].handle` | string | | |
| `internal_shipping_methods[].cost_type` | string | | |
| `internal_shipping_methods[].cost_language_string` | string \| null | | |
| `shop` | object | | |
| `shop.base_currency_code` | string | | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. Length: min 3, max 3. |
| `line_items` | (LineItemProduct \| LineItemCustom)[] | | |
| `line_items[].type` | "product" | | |
| `line_items[].spark_item_key` | string | | Length: max 32. |
| `line_items[].spark_variant_id` | string | | Length: max 36. |
| `line_items[].sku` | string | | |
| `line_items[].product_variant_external_id` | string | | eCommerce platform ID of Product Variant |
| `line_items[].product_external_id` | string | | eCommerce platform ID of Product |
| `line_items[].quantity` | integer | | |
| `line_items[].unit_price` | number | | Net price of a unit |
| `line_items[].custom_attributes` | object[] | | Custom attributes allow arbitrary data to be attached to a line item |
| `line_items[].custom_attributes[].key` | string | | |
| `line_items[].custom_attributes[].value` | string | | |
| `line_items[].options` | object[] \| null | | |
| `line_items[].options[].group` | string | | |
| `line_items[].options[].value` | string | | |
| `line_items[].name` | string | | Length: max 128. |
| `ignite_state` | object | | Context which was set by a previous response from /checkout/calculate |
| `ignite_checkout_context` | object \| null | | Extra context provided by the checkout frontend. This allows passing arbitrary platform-specific data that might be needed by the platform's checkout process. For example, for BigCommerce, this could be used to pass a `channel_id` from the store theme to the ignite integration in order to support multi-channel stores. |
| `shipping_method_source` | "sparklayer" \| "platform" | | Specifies the store's configured source for retrieving shipping methods during checkout. When `sparklayer`, a `null` `shipping_line` means the cart has no shipping charge, and no platform rate is fetched or applied. Absent is treated as `platform`. |
| `payment_type` | "upfrontPayment" \| "paymentOnAccount" \| "paymentByInvoice" \| "quote" | | |
| `sales_agent` | object \| null | | |
| `sales_agent.id` | string | Yes | SparkLayer ID of Sales Agent |
| `sales_agent.email` | string (email) | Yes | |
| `sales_agent.accounting_id` | string \| null | | |
| `company_user` | object \| null | | |
| `company_user.id` | string | Yes | SparkLayer ID of Customer |
| `company_user.email` | string (email) | Yes | |
| `company_user.external_id` | string | Yes | eCommerce platform ID of Customer |
| `company_user.accounting_id` | string \| null | | |
| `additional_info` | string \| null | | An optional note to be added to the order. |
| `po_number` | string \| null | | PO number for the purchase |
| `shipping_requested_date` | string (date-time) \| null | | The date requested for the delivery to arrive |
| `custom_fields` | object \| null | | Custom fields to be added to the order. These are customer defined and dynamic. |
| `discount_data` | object \| null | | |
| `discount_data.sub_total_pre_discount` | object | Yes | |
| `discount_data.sub_total_pre_discount.net` | number (float) | Yes | |
| `discount_data.sub_total_discount` | object | Yes | |
| `discount_data.sub_total_discount.net` | number (float) | Yes | |
| `discount_data.shipping_pre_discount` | object | | |
| `discount_data.shipping_pre_discount.net` | number (float) | Yes | |
| `discount_data.shipping_discount` | object | | |
| `discount_data.shipping_discount.net` | number (float) | Yes | |
| `discount_data.line_item_discounts` | object[] | Yes | |
| `discount_data.line_item_discounts[].pre_discount` | object | Yes | |
| `discount_data.line_item_discounts[].pre_discount.net` | number (float) | Yes | |
| `discount_data.line_item_discounts[].discount` | object | Yes | |
| `discount_data.line_item_discounts[].discount.net` | number (float) | Yes | |
| `discount_data.line_item_discounts[].sku` | string | Yes | |
| `discount_data.line_item_discounts[].item_key` | string | Yes | |
| `discount_data.discount_slugs` | string[] | Yes | |
| `discount_coupon_codes` | string[] \| null | | A list of all the coupon codes applied to the order |

```json
{
  "cart_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
  "customer": {
    "id": "cu_1",
    "email": "buyer@example.com",
    "external_id": "CUS1234",
    "accounting_id": "<accounting_id>",
    "default_billing_address_id": "<default_billing_address_id>",
    "default_shipping_address_id": "<default_shipping_address_id>",
    "temporary_external_address_ids": [
      "<temporary_external_address_ids>"
    ],
    "payment_on_account": {
      "credit_limit": 0,
      "balance": 0,
      "currency_code": "<currency_code>",
      "net_terms": "7_days"
    }
  },
  "currency_code": "gbp",
  "billing_address": {
    "title": "Mr",
    "first_name": "Bob",
    "last_name": "Jones",
    "company": "Tom Jones Climbing Ltd",
    "address_line1": "Example Industrial Estate",
    "address_line2": "North Country",
    "city": "Cityland",
    "region_name": "California",
    "region_code": "CA",
    "postal_code": "12345",
    "country_code": "US",
    "phone": "+44 (0) 123456789",
    "is_default_shipping": true,
    "is_default_billing": true,
    "is_temporary": true
  },
  "shipping_address": {
    "title": "Mr",
    "first_name": "Bob",
    "last_name": "Jones",
    "company": "Tom Jones Climbing Ltd",
    "address_line1": "Example Industrial Estate",
    "address_line2": "North Country",
    "city": "Cityland",
    "region_name": "California",
    "region_code": "CA",
    "postal_code": "12345",
    "country_code": "US",
    "phone": "+44 (0) 123456789",
    "is_default_shipping": true,
    "is_default_billing": true,
    "is_temporary": true
  },
  "shipping_line": {
    "type": "platform",
    "id": "<id>",
    "name": "<name>",
    "price": 4.8,
    "tax_rate": 0.2
  },
  "internal_shipping_methods": [
    {
      "title": "<title>",
      "price_v2": {
        "tax_rate": 0,
        "net": 0,
        "gross": 0,
        "currency_code": "<currency_code>"
      },
      "handle": "<handle>",
      "cost_type": "<cost_type>",
      "cost_language_string": "<cost_language_string>"
    }
  ],
  "shop": {
    "base_currency_code": "gbp"
  },
  "line_items": [
    {
      "type": "product",
      "spark_item_key": "00a0c91e6bf600a0c91e6bf",
      "spark_variant_id": "8ac52999-d163-4d68-ae30-a5f0c089ed79",
      "sku": "EXAMPLE-SKU",
      "product_variant_external_id": "PROD123456",
      "product_external_id": "PROD1234",
      "quantity": 10,
      "unit_price": 4.8,
      "custom_attributes": [
        {
          "key": "<key>",
          "value": "<value>"
        }
      ],
      "options": [
        {
          "group": "<group>",
          "value": "<value>"
        }
      ]
    }
  ],
  "ignite_state": {},
  "ignite_checkout_context": {
    "channel_id": 12345
  },
  "shipping_method_source": "sparklayer",
  "payment_type": "upfrontPayment",
  "sales_agent": {
    "id": "cu_1",
    "email": "buyer@example.com",
    "accounting_id": "<accounting_id>"
  },
  "company_user": {
    "id": "cu_1",
    "email": "buyer@example.com",
    "external_id": "CUS1234",
    "accounting_id": "<accounting_id>"
  },
  "additional_info": "<additional_info>",
  "po_number": "PO-001",
  "shipping_requested_date": "2020-01-01T00:00:00+02:00",
  "custom_fields": {},
  "discount_data": {
    "sub_total_pre_discount": {
      "net": 0
    },
    "sub_total_discount": {
      "net": 0
    },
    "shipping_pre_discount": {
      "net": 0
    },
    "shipping_discount": {
      "net": 0
    },
    "line_item_discounts": [
      {
        "pre_discount": {
          "net": 0
        },
        "discount": {
          "net": 0
        },
        "sku": "<sku>",
        "item_key": "<item_key>"
      }
    ],
    "discount_slugs": [
      "<discount_slugs>"
    ]
  },
  "discount_coupon_codes": [
    "<discount_coupon_codes>"
  ]
}
```

### Responses your service returns

#### 201: Checkout complete success

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `line_items` | object[] | | |
| `line_items[].spark_item_key` | string | Yes | |
| `line_items[].tax_lines` | object[] | Yes | |
| `line_items[].tax_lines[].rate` | number | | Tax rate |
| `line_items[].tax_lines[].price` | number | | Tax amount |
| `platform_shipping_line` | object | | The shipping line applied to the order in the eCommerce platform. Determines price and tax amounts for SparkLayer. |
| `platform_shipping_line.type` | "platform" \| "sparklayer" | | |
| `platform_shipping_line.id` | string | | |
| `platform_shipping_line.name` | string | | |
| `platform_shipping_line.price` | number | | Net of tax |
| `platform_shipping_line.tax_rate` | number | | |

```json
{
  "line_items": [
    {
      "spark_item_key": "<spark_item_key>",
      "tax_lines": [
        {
          "rate": 0.2,
          "price": 1
        }
      ]
    }
  ],
  "platform_shipping_line": {
    "type": "platform",
    "id": "<id>",
    "name": "<name>",
    "price": 4.8,
    "tax_rate": 0.2
  },
  "checkout_url": "https://checkout-bobs-store.com/checkout/1234/payment"
}
```

#### 401: Auth Failure

#### 500: System Exception


---

# List entities for a sync

URL: https://docs.sparklayer.io/ignite/api/list-entities
Operation: `GET /v1/{siteEnv}/{siteId}/sync/{syncDataType}` (operationId `getPage`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

SparkLayer calls this endpoint during a full sync to page through every entity of the given type. Return one page of entities and a `next_page` value; SparkLayer requests the next page with it in the `page` query parameter. Return an empty string or `null` for `next_page` to end the sync.

`GET /v1/{siteEnv}/{siteId}/sync/{syncDataType}`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
GET /v1/live/bobs-store/sync/products HTTP/1.1
Host: ignite.example.com
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |
| `syncDataType` | "customers" \| "products" \| "purchases" \| "stock" | Yes | The type of entity to list. Example: `products` |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | string | | The page number to return |

### Responses your service returns

#### 200: A list of entity ids

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | object[] | | |
| `items[].id` | string | | The id of the entity |
| `items[].payload` | string \| null | | Optional - the payload to send back to the integration during the item sync |
| `next_page` | string \| null | | The next page id of entity ids. An empty string or null ends the full sync. |

```json
{
  "items": [
    {
      "id": "<id>",
      "payload": "<payload>"
    }
  ],
  "next_page": "<next_page>"
}
```

#### 422: Unprocessable entity

`application/problem+json`: the standard error body (below).

#### 429: Rate limit exceeded

#### 500: Internal server error

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `api_response` | string | | API response error for sync log |
| `friendly_error` | string | | Friendly error message to display in sync log |
| `external_url` | string | | A url to access to problem on |
| `visible_name` | string | | A display name for the problem |

```json
{
  "api_response": "<api_response>",
  "friendly_error": "<friendly_error>",
  "external_url": "<external_url>",
  "visible_name": "<visible_name>"
}
```

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string (uri) | Yes | A URI reference that identifies the problem. |
| `title` | string | Yes | A short, human-readable summary of the problem type. |
| `status` | integer | | The HTTP status code generated by the origin server for this occurrence of the problem. |
| `detail` | string | | A human-readable explanation specific to this occurrence of the problem. |

```json
{
  "type": "about:blank",
  "title": "invalid-request-contents",
  "status": 0,
  "detail": "<detail>"
}
```


---

# Fetch an entity

URL: https://docs.sparklayer.io/ignite/api/fetch-entity
Operation: `POST /v1/{siteEnv}/{siteId}/sync/{syncDataType}/{entityId}` (operationId `getEntity`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

Fetch an entity from the platform.

`POST /v1/{siteEnv}/{siteId}/sync/{syncDataType}/{entityId}`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
POST /v1/live/bobs-store/sync/products/1234567890 HTTP/1.1
Host: ignite.example.com
Content-Type: application/json

{
  "payload": "<payload>"
}
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |
| `syncDataType` | "customers" \| "products" \| "purchases" \| "stock" | Yes | The type of entity to fetch. Example: `products` |
| `entityId` | string | Yes | The entity's ID on your platform. Example: `1234567890` |

### Request body (`application/json`) (optional)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `payload` | string \| null | | Optional - the payload to send back to the integration during the item sync |

```json
{
  "payload": "<payload>"
}
```

### Responses your service returns

#### 200: Entity fetched successfully

One of these:

**CustomerData**: Customer data representing the SparkLayer Customer object.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `external_id` | string | | External id of the entity |
| `external_url` | string | | A url to access to entity on |
| `visible_name` | string | | A display name for the entity |
| `customer_v2` | string | | base64 encoded string |
| `customer_v2_deactivate` | boolean | | whether or not to deactivate the customer |

**ProductData**: Product data representing the SparkLayer Product object.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `external_id` | string | | External id of the entity |
| `external_url` | string | | A url to access to entity on |
| `visible_name` | string | | A display name for the entity |
| `product_v2_delete` | boolean | | whether or not to delete the product |
| `product_v2_discontinue` | boolean | | whether or not to discontinue the product |
| `product_v2` | string | | base64 encoded string |
| `batch_stock_v1` | string | | base64 encoded string |
| `batch_pricing_v1` | string | | base64 encoded string |

**PurchaseData**: Purchase data representing the SparkLayer Purchase object.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `external_id` | string | | External id of the entity |
| `external_url` | string | | A url to access to entity on |
| `visible_name` | string | | A display name for the entity |
| `purchase_v1` | string | | base64 encoded string |

**StockData**: Stock data representing the SparkLayer Stock object.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `external_id` | string | | External id of the entity |
| `external_url` | string | | A url to access to entity on |
| `visible_name` | string | | A display name for the entity |
| `batch_stock_v1` | string | | base64 encoded string |

```json
{
  "external_id": "<external_id>",
  "external_url": "<external_url>",
  "visible_name": "<visible_name>",
  "customer_v2": "<customer_v2>",
  "customer_v2_deactivate": true
}
```

#### 400: Invalid request, such as a payload that cannot be decoded

#### 401: Auth Failure

#### 404: Not Found

One of these:

- **Problem**: the standard error body (below).

**EntityDoesNotExist**: The integration indicated that the entity does not exist.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string (uri) | Yes | A URI reference that identifies the problem. |
| `title` | "entity-does-not-exist" | Yes | |
| `status` | 404 | | |
| `detail` | string | | A human-readable explanation specific to this occurrence of the problem. |

```json
{
  "type": "about:blank",
  "title": "invalid-request-contents",
  "status": 404,
  "detail": "<detail>"
}
```

#### 422: Unprocessable entity. The sync service does not check the content type, and the SparkLayer integrations send this body as application/json.

`application/problem+json`:

One of these:

- **Problem**: the standard error body (below).

**EntityConfigurationError**: The integration indicated that the entity is not correctly configured and therefore cannot be synced.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string (uri) | Yes | A URI reference that identifies the problem. |
| `title` | "entity-configuration-error" | Yes | |
| `status` | 422 | | |
| `detail` | string | | A human-readable explanation specific to this occurrence of the problem. |
| `external_id` | string | | External id of the entity |
| `external_url` | string | | A url to access to entity on |
| `visible_name` | string | | A display name for the entity |
| `api_response` | string | | API response error for sync log |
| `friendly_error` | string | | Friendly error message to display in sync log |

```json
{
  "type": "about:blank",
  "title": "invalid-request-contents",
  "status": 422,
  "detail": "<detail>"
}
```

`application/json`:

One of these:

- **Problem**: the standard error body (below).

**EntityConfigurationError**: The integration indicated that the entity is not correctly configured and therefore cannot be synced.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string (uri) | Yes | A URI reference that identifies the problem. |
| `title` | "entity-configuration-error" | Yes | |
| `status` | 422 | | |
| `detail` | string | | A human-readable explanation specific to this occurrence of the problem. |
| `external_id` | string | | External id of the entity |
| `external_url` | string | | A url to access to entity on |
| `visible_name` | string | | A display name for the entity |
| `api_response` | string | | API response error for sync log |
| `friendly_error` | string | | Friendly error message to display in sync log |

```json
{
  "type": "about:blank",
  "title": "invalid-request-contents",
  "status": 422,
  "detail": "<detail>"
}
```

#### 429: Rate limit exceeded

#### 500: System Exception

#### Other statuses: Error Response

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string (uri) | Yes | A URI reference that identifies the problem. |
| `title` | string | Yes | A short, human-readable summary of the problem type. |
| `status` | integer | | The HTTP status code generated by the origin server for this occurrence of the problem. |
| `detail` | string | | A human-readable explanation specific to this occurrence of the problem. |

```json
{
  "type": "about:blank",
  "title": "invalid-request-contents",
  "status": 0,
  "detail": "<detail>"
}
```


---

# Trigger a data sync

URL: https://docs.sparklayer.io/ignite/api/trigger-a-data-sync
Operation: `POST /v1/{siteEnv}/{siteId}/status/{syncDataType}` (operationId `triggerDataSync`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

Allow internal users (e.g. support staff) to trigger a manual sync external to the standard process.

`POST /v1/{siteEnv}/{siteId}/status/{syncDataType}`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
POST /v1/live/bobs-store/status/products HTTP/1.1
Host: ignite.example.com
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |
| `syncDataType` | "customers" \| "products" \| "purchases" \| "merchant" \| "customer_groups" | Yes | Example: `products` |

### Responses your service returns

#### 201: Initiated Data Sync

#### 400: Unable to trigger another data sync as there is one in progress

#### 401: Auth Failure

#### 500: System Exception


---

# Get metafield configuration

URL: https://docs.sparklayer.io/ignite/api/get-metafield-configuration
Operation: `GET /v1/{siteEnv}/{siteId}/metafield-configuration` (operationId `getMetafieldConfiguration`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

Returns a list of all SparkLayer metafield schema keys supported by the platform and the current configuration state for each key

`GET /v1/{siteEnv}/{siteId}/metafield-configuration`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
GET /v1/live/bobs-store/metafield-configuration HTTP/1.1
Host: ignite.example.com
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |

### Responses your service returns

#### 200: A successful response

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].key` | "customer.accounting_id" \| "customer.available_shipping_addresses_ids" \| "customer.billing_address_id" \| "customer.shipping_address_id" \| "customer.company_name" \| "customer.discount_percentage" \| "customer.payment_on_account" \| "customer.parent_customer_id" \| "customer.price_lists" \| "customer.sales_agent_groups" \| "product_variant.max_order_parent_quantity" \| "product_variant.max_order_quantity" \| "product_variant.min_order_parent_quantity" \| "product_variant.min_order_quantity" \| "product_variant.min_stock_level" \| "product_variant.pack_size" \| "product_variant.reserve_stock_quantity" \| "product_variant.restock_date" \| "product_variant.rrp" \| "product_variant.settings" \| "product_variant.stock_location_data" | | |
| `[].state` | "enabled" \| "not_configured" | | |

```json
[
  {
    "key": "customer.accounting_id",
    "state": "enabled"
  }
]
```

#### 404: Not found

#### 500: System exception


---

# Enable a metafield

URL: https://docs.sparklayer.io/ignite/api/enable-a-metafield
Operation: `POST /v1/{siteEnv}/{siteId}/metafield-configuration/enable` (operationId `enableMetafield`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

Enables the specified key within the platform

`POST /v1/{siteEnv}/{siteId}/metafield-configuration/enable`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
POST /v1/live/bobs-store/metafield-configuration/enable HTTP/1.1
Host: ignite.example.com
Content-Type: application/json

{
  "key": "customer.accounting_id",
  "name": "<name>"
}
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | "customer.accounting_id" \| "customer.available_shipping_addresses_ids" \| "customer.billing_address_id" \| "customer.shipping_address_id" \| "customer.company_name" \| "customer.discount_percentage" \| "customer.payment_on_account" \| "customer.parent_customer_id" \| "customer.price_lists" \| "customer.sales_agent_groups" \| "product_variant.max_order_parent_quantity" \| "product_variant.max_order_quantity" \| "product_variant.min_order_parent_quantity" \| "product_variant.min_order_quantity" \| "product_variant.min_stock_level" \| "product_variant.pack_size" \| "product_variant.reserve_stock_quantity" \| "product_variant.restock_date" \| "product_variant.rrp" \| "product_variant.settings" \| "product_variant.stock_location_data" | Yes | |
| `name` | string | Yes | The readable name for the metafield |

```json
{
  "key": "customer.accounting_id",
  "name": "<name>"
}
```

### Responses your service returns

#### 204: Successful operation

#### 400: Error handling request such as an unsupported key

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error_code` | "metafield-key-unsupported-by-platform" | | Machine-readable error code |

```json
{
  "error_code": "metafield-key-unsupported-by-platform"
}
```

#### 404: Not found

#### 500: System exception


---

# Verify storefront authentication

URL: https://docs.sparklayer.io/ignite/api/verify-authentication
Operation: `POST /v1/{siteEnv}/{siteId}/authentication/verify` (operationId `authenticationVerify`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

Verifies authentication data, such as a JWT, provided by the platform on the front end.

`POST /v1/{siteEnv}/{siteId}/authentication/verify`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
POST /v1/live/bobs-store/authentication/verify HTTP/1.1
Host: ignite.example.com
Content-Type: application/json

{
  "data": "<data>"
}
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |

### Request body (`application/json`) (required)

Data to verify. It must be possible to derive the platform external ID for the customer from this data in order to satisfy the response criteria.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | string | Yes | |

```json
{
  "data": "<data>"
}
```

### Responses your service returns

#### 200: Data is verified.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `customer` | object | | |
| `customer.external_id` | string | Yes | eCommerce platform ID of Customer |

```json
{
  "customer": {
    "external_id": "CU1234"
  }
}
```

#### 400: The request is invalid.

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable detail of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Human-readable summary of the error |
| `type` | string | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```