# Import order history from your ERP

URL: https://docs.sparklayer.io/help/guides/import-order-history

Load past orders from NetSuite or another ERP into SparkLayer once, so customers see them in My Account and Pulse shows your full sales history.

> **Quick summary**
>
> - You'll end up with your past B2B orders in SparkLayer: in your customers' order history in [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md), and in [Pulse](https://docs.sparklayer.io/help/pulse.md) on the dates they were placed.
> - You export the orders from your ERP. A developer, an agency or an AI assistant sends them to SparkLayer with the Purchasing API.
> - Are the orders in Shopify? Mark them for import there instead: see [Show imported or manual orders in My Account](https://docs.sparklayer.io/help/guides/show-imported-orders.md).

Pulse and My Account only know about the orders that are in SparkLayer: see [Which orders Pulse counts](https://docs.sparklayer.io/help/pulse.md#which-orders-pulse-counts). Orders from before you started with SparkLayer, or taken by phone and keyed into your ERP, are missing until you send them. A one-off import fills that gap.

## How it works

A one-off order history import:

1. **You export**: Orders, shipments, returns and cancellations from your ERP, as a spreadsheet
2. **They import**: Your developer, agency or AI assistant sends each order with the Purchasing API
3. **You check**: Orders show in My Account and in Pulse

- **Orders show as they are in your ERP.** Each one keeps its order number, date, products, prices and currency, and shows what shipped, what was cancelled and what came back.
- **Orders aren't sent to your eCommerce platform.** They only appear in SparkLayer.
- **Nothing keeps syncing afterwards.** The import is a snapshot. To change an order later, send it again.
- **It's safe to run again.** Sending an order that's already imported updates it rather than adding a copy, so you can fix a few orders and rerun the import.
- **Customers aren't emailed.** SparkLayer only emails about an order when someone posts a message on it: see [Emails the timeline sends](https://docs.sparklayer.io/help/customers/timeline.md#emails-sent).

## Before you start

- **Every customer in SparkLayer**, including customers who no longer order. An order only shows for a customer SparkLayer knows. See [Managing customers](https://docs.sparklayer.io/help/customers/managing-customers.md).
- **A way to match customers**: their email address, or their customer ID on your eCommerce platform, in your ERP.
- **Opening balances for customers who pay on account**, dated after the newest order you'll import, so old orders don't change what they owe. See [Show a real-time account balance](https://docs.sparklayer.io/help/ordering/payment-methods.md#payments---account-balance).
- **Orders that are already in SparkLayer left out**, such as orders placed through SparkLayer, or they'll show twice.
- **An API key in Test mode**, to try the import on a few orders first. See [Test mode](https://docs.sparklayer.io/help/dashboard/test-mode.md).

Customers who no longer order can be added as inactive, so their orders count in Pulse but they can't sign in. Whoever runs the import can do this with the [Customers API](https://docs.sparklayer.io/developers/api/customers.md).

## Export your orders

Export one row for each product in each shipment, cancellation or return, with these columns. Most ERPs can export this from sales orders, item fulfilments, return authorisations and credit notes.

| Column | What to put in it |
| --- | --- |
| `order_number` | Your order number. Customers see it in My Account, and it's how a rerun finds the order. |
| `order_date` | When the order was placed, with the time and time zone, such as `2024-03-14T09:30:00Z`. |
| `customer_email` | The customer's email address, to match them in SparkLayer. Or use their customer ID on your eCommerce platform. |
| `currency` | The order's currency, such as `EUR`. |
| `base_currency_rate` | The rate to your store's main currency on the order date, such as `0.85`. Use `1` for orders in your main currency. Pulse reports in your main currency. |
| `po_number` | The customer's purchase order number, if any. |
| `package_type` | `shipment`, `cancelled` or `return`. Use `processing` for anything not yet shipped. |
| `package_number` | Your reference for the shipment, cancellation or return, such as a delivery note or return number. |
| `package_date` | When it shipped, was cancelled, or the return started. Empty for `processing`. |
| `return_completed_date` | For returns, when the return was completed. |
| `sku`, `product_name`, `variant_name` | The product, as it was ordered. |
| `quantity` | How many were in this shipment, cancellation or return. |
| `line_net`, `line_discount`, `line_tax` | The price before tax after discounts, the discount already taken off, and the tax, for this quantity. |
| `shipping_method`, `shipping_net`, `shipping_tax` | The shipping charge, on one row of the order only, usually the first shipment. |
| `carrier`, `tracking_number` | For shipments, if you have them. |

- **A returned product appears twice**: once in its shipment, and again as a `return` row.
- **Every unit ordered is in a `shipment`, `cancelled` or `processing` row.** Add up those rows and you get the quantities ordered.

This template has 2 orders. `SO-10452` shipped in 2 parts and 1 seat was returned. `SO-10467` shipped 3 grips and cancelled 2.

```csv title="order-history-template.csv"
order_number,order_date,customer_email,currency,base_currency_rate,po_number,package_type,package_number,package_date,return_completed_date,sku,product_name,variant_name,quantity,line_net,line_discount,line_tax,shipping_method,shipping_net,shipping_tax,carrier,tracking_number
SO-10452,2024-03-14T09:30:00Z,buyer@example.com,EUR,0.85,PO-7781,shipment,SO-10452-1,2024-03-18T14:00:00Z,,HB-200,Handlebar grip,Black,6,72.00,18.00,14.40,Standard delivery,15.00,3.00,DPD,15501234567890
SO-10452,2024-03-14T09:30:00Z,buyer@example.com,EUR,0.85,PO-7781,shipment,SO-10452-1,2024-03-18T14:00:00Z,,SD-110,Comfort seat,,4,200.00,0.00,40.00,,,,DPD,15501234567890
SO-10452,2024-03-14T09:30:00Z,buyer@example.com,EUR,0.85,PO-7781,shipment,SO-10452-2,2024-03-25T11:15:00Z,,HB-200,Handlebar grip,Black,4,48.00,12.00,9.60,,,,DPD,15501234567999
SO-10452,2024-03-14T09:30:00Z,buyer@example.com,EUR,0.85,PO-7781,return,RMA-2231,2024-04-02T10:00:00Z,2024-04-09T16:00:00Z,SD-110,Comfort seat,,1,50.00,0.00,10.00,,,,,
SO-10467,2024-05-02T08:00:00Z,orders@example.org,GBP,1,PO-112,shipment,SO-10467-1,2024-05-06T15:30:00Z,,HB-200,Handlebar grip,Black,3,36.00,0.00,7.20,Standard delivery,10.00,2.00,Royal Mail,RM123456789GB
SO-10467,2024-05-02T08:00:00Z,orders@example.org,GBP,1,PO-112,cancelled,SO-10467-C1,2024-05-03T09:00:00Z,,HB-200,Handlebar grip,Black,2,24.00,0.00,4.80,,,,,
```

If your ERP holds payments, export them too: the order number, payment date, amount and a payment reference. Refunds are negative amounts.

## Choose who runs the import

| Who | What to give them |
| --- | --- |
| **Your developer or agency** | Your export, and [Send orders to SparkLayer](https://docs.sparklayer.io/developers/api/purchasing/send-orders.md): every rule for building the orders, with a complete example. |
| **An AI assistant**, such as Claude or ChatGPT | The **Import order history** prompt in [Build with AI](https://docs.sparklayer.io/developers/build-with-ai.md#order-history). Add a line about your ERP and your export, then open it in your assistant. It reads the docs and writes the import for you to review. |

Either way, they'll need an API key: see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

## Check it worked

- **In My Account**, signed in as a customer, their past orders show in **Recent Activity**, with the right status. 
- **In Pulse**, imported orders show on [Orders](https://docs.sparklayer.io/help/pulse/orders.md) on the dates they were placed. Pulse picks up new orders within about 4 hours.
- **A few totals match your ERP**, including an order that was part-shipped and one with a return.

## FAQs

**Are imported orders sent to Shopify or our ERP?**

No. They only appear in SparkLayer: in My Account and in Pulse. SparkLayer doesn't send them anywhere else.

**Can we run the import again?**

Yes. Each order is matched on its order number, so sending it again updates it instead of adding a copy. Fix the orders that failed and rerun the import.

**Why is an imported order's total lower than in our ERP?**

SparkLayer leaves cancelled items out of an order's total and takes returned items off it. The total is what the customer kept. Check the order's cancellation and return rows if it still looks wrong.

**Why doesn't an imported order show in My Account?**

The order is usually for a customer SparkLayer doesn't know, or matched to the wrong one. Check the customer is at **Customers** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/customers/list)), or **SparkLayer Wholesale > Customers** in the Shopify app, and that the import matched their email address or customer ID.

**What does a Varied status mean?**

The order's items ended up in different states, such as some shipped and some cancelled. The order details show what happened to each item.

**Will imported orders change what customers owe?**

They can. Each order adds its total to the customer's account balance, and each payment takes it off. Give customers who pay on account an opening balance dated after the newest imported order, and older orders don't count. See [Show a real-time account balance](https://docs.sparklayer.io/help/ordering/payment-methods.md#payments---account-balance).

**Do imported orders show as paid?**

Only if the import says so. SparkLayer works out payment status from payments for orders placed from 6 March 2026. For older orders, your developer can send the payment status with each order.

## Next steps

- [Send orders to SparkLayer](https://docs.sparklayer.io/developers/api/purchasing/send-orders.md): The developer guide: packages, statuses, currencies and a complete example
- [Build with AI](https://docs.sparklayer.io/developers/build-with-ai.md#order-history): The ready-made prompt for an AI assistant
- [Pulse](https://docs.sparklayer.io/help/pulse.md): Where imported orders show for your sales team