CSV, JSON and XML files

This page is for whoever makes the files your system sends to the tablets. It covers the shape of each format. The column names are in the Import field reference, and how files are named and collected is in Connecting your ERP.

If you are not technical: send the CSV samples below to whoever runs your stock or accounts system and ask for the same columns. That is usually all it takes.

Sample files

These are the files the app itself writes into your folder or server when it first connects (the _SAMPLE_ files), downloaded here so you can see them before you have a tablet. They are exactly what the app’s default import profiles read: the app’s own tests check every column in them against those profiles.

Each one is a header row and one example record with every column filled in. It imports exactly as it is; the app’s tests check that. Keep the header row and replace the example with your own data. Any column except the record’s own code may be left blank.

Every kind of record has a reference page: each field explained, which are required, the exact format, and the same example in CSV, JSON and XML.

Columns that hold several values separate them with |. Volume prices (QtyBreaks) are quantity and price pairs: 24:9.50|48:8.75 means 9.50 each from 24, and 8.75 each from 48. Contracted prices (PriceLists) work the same way with the price list name: TRADE:11.50|WHOLESALE:9.99.

Files your system sends (CSV)

Rename a sample before it goes in Inbound: a file whose name starts _SAMPLE_ is never imported. Products.csv is fine; so is Products_2026-11-01.csv.

Files the app sends back

What arrives in Outbound with the default export templates, in all three formats: each is a real export of one sample order (two lines, a promotion and a delivery charge) or one new customer, exactly as the app writes it. To change them, see Export templates.

Which format to use

If you are not sure, use CSV. A CSV file is a spreadsheet saved as plain text: Excel makes one with Save As › CSV, and almost every accounts or ERP system can export one.

JSON and XML work just as well, for every kind of record, so use one of them if your system produces it more easily than a CSV. Nothing needs changing in the app’s settings to switch: it reads each file in the format its name says.

You can mix formats, say products as XML and customers as CSV. The app tells them apart by the end of the file name: .csv (or .txt) for CSV, .json for JSON and .xml for XML.

Field names are different in each format. A product code goes in a column called ItemCode in a CSV file, but in a field called sku in JSON and SKU in XML. The field reference gives all three names for every field.

Rules for every format

Text encoding: UTF-8, with or without a byte-order mark, or Windows-1252 (what older Windows software writes). Accented names and the £ and € signs come through either way.
Numbers and money can be written the way your system writes them: £1,299.00, 1.299,00 and 1299 are all read correctly. The rules are in Connecting your ERP.
Dates: 2026-11-01 (ISO) is always read correctly. Other shapes are read in the order of the date format set in the app.
Yes and no: true, yes, y, 1 and the opposites, in any case.
A blank leaves the record as it was. Send only what you have; a partial file updates what it mentions.
A value that cannot be read stops that one row, and the sync log names the row, the column and the value. The rest of the file still imports.

CSV

Comma-separated, with a header row. Column names are matched ignoring case and surrounding spaces, and columns the app does not use are ignored, so you can send your whole export.
Put a value in double quotes when it contains a comma, a line break or a quote, and double any quote inside it: "Ben & Jerry's ""Original""". Every spreadsheet and database export does this already.
End the file with a line break. A file that stops partway through its last row is treated as still being written, and left for the next sync.
Lists inside one cell, such as categories or tags, are separated with |: Spirits|Gin.

JSON

A list of records, one object per record:

JSON

[
  {
    "sku": "PL003",
    "title": "Andes Reserve 75cl",
    "rrp": "13.99",
    "prices": { "TRADE": 9.99 },
    "qty_breaks": { "24": 9.50 },
    "status": "Active"
  }
]

That record is one the app’s own tests import. The list can also sit inside an object, as many systems export it ({"products": [ … ]}): the app uses the first list it finds. A file that is not a list of records is refused with a message saying so, rather than read as an empty catalogue.

Price lists and quantity breaks are real objects, as above, not text.

XML

One element per record, named for what it is, anywhere in the file:

Records	Element
Products	`<Product>`
Customers	`<Customer>`
Categories	`<Category>`
Promotions	`<Promotion>`
Announcements	`<Announcement>`
Delivery methods	`<DeliveryMethod>`
Users	`<User>`

The fields are child elements. The outer element can be called anything:

XML

<?xml version="1.0" encoding="UTF-8"?>
<Catalogue>
  <Product>
    <SKU>PL004</SKU>
    <Title>Andes Reserve 75cl</Title>
    <RRP>13.99</RRP>
    <Status>Active</Status>
    <Prices>
      <TRADE>9.99</TRADE>
      <WHOLESALE>8.50</WHOLESALE>
    </Prices>
  </Product>
</Catalogue>

Again, taken from the app’s tests. The record element’s name matters: the field reference writes a product’s code as Item/SKU, but the app looks for <Product> elements, and a file of <Item> elements imports nothing. Only the part after the last / has to match a child element, and case does not matter. Nested elements such as a billing address are read as Billing/City, or just City.

Escape & as & and < as < inside values, as any XML writer will.

Checking a file before it goes live

On the tablet, Settings › Data Integration › Sync & Integration › Receiving › Try a file from this tablet reads one file and says how it went, without syncing anything. Existing records are never deleted by it.