Import order history from your ERP
Pulse and My Account only know about the orders that are in SparkLayer: see 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
You export
They import
You check
- 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.
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.
- 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.
- 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.
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.
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
returnrow. - Every unit ordered is in a
shipment,cancelledorprocessingrow. 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.
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: 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. 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.
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 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
No. They only appear in SparkLayer: in My Account and in Pulse. SparkLayer doesn't send them anywhere else.
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.
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.
The order is usually for a customer SparkLayer doesn't know, or matched to the wrong one. Check the customer is at Customers (opens in your SparkLayer Dashboard in a new tab), and that the import matched their email address or customer ID.
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.
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.
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
Last updated