---
title: 'From Square'
url: 'https://chronoslice.app/docs/moving-to-chronoslice/from-square'
markdown: 'https://chronoslice.app/docs/moving-to-chronoslice/from-square.md'
date: '2026-11-14'
description: "The Square importer brings your customers, invoices and recurring invoices into ChronoSlice from the server's command line. Recurring invoices arrive paused, so nobody is billed twice. This page shows the steps, from a trial run to switching on each recurring invoice. What comes across Customers w…"
taxonomy:
  kb_category:
    - 'Moving to ChronoSlice'
---

[Docs](https://chronoslice.app/docs)

 [Contact support](https://chronoslice.app/help/new) 

Docs menu

# From Square

Import customers, invoices with their payments and fees, and recurring invoices from Square, without billing anyone twice.

 Updated Nov 14, 2026 4 min read

The Square importer brings your customers, invoices and recurring invoices into ChronoSlice from the server's command line. Recurring invoices arrive paused, so nobody is billed twice. This page shows the steps, from a trial run to switching on each recurring invoice.

## What comes across

- **Customers** with invoices become clients, with their billing email and address. A customer who only has cancelled invoices comes over only if your mapping file names them.
- **Invoices** come over with their lines, their payments, and Square's fees. Draft invoices stay in Square.
- **Scheduled recurring invoices** become recurring invoices in ChronoSlice. They arrive paused.

The importer only reads from Square. It sends GET requests, plus a read-only lookup of orders. Nothing in Square is changed.

## Before you start

- Install ChronoSlice and have your account ready. See [Install on Linux](https://chronoslice.app/docs/installing/install-on-linux) and [The first account](https://chronoslice.app/docs/installing/the-first-account).
- Create a Square access token. In Square's developer dashboard, open your app, then **Production**, then **Access token**. Replace the token in Square when you've finished, if you'd rather not leave it in use.
- Imports are refused while the server is read-only after the trial.

## Try it first

A dry run reads from Square and shows what would happen, and keeps nothing:

```sh
read -rs SQUARE_ACCESS_TOKEN && export SQUARE_ACCESS_TOKEN
sudo -u chronoslice env CHRONOSLICE_DB=sqlite:///var/lib/chronoslice/chronoslice.db \
  SQUARE_ACCESS_TOKEN="$SQUARE_ACCESS_TOKEN" chronoslice import square --dry-run
```

It prints a summary as JSON: how many clients matched or were created, customers left out, invoices new, updated or skipped, payments, the fees and billed amounts in cents, the number of recurring schedules, and any warnings. Then it says `(dry run: nothing was kept)`.

## Decide which client each customer becomes

By default each Square customer with invoices goes to a client of the same name, or becomes a new client. To decide yourself, give a mapping file with `--mapping`. It's JSON that names each Square customer by id:

```json
{
  "CUSTOMER_ID_1": {"choice": "client", "client_id": "A ChronoSlice client id"},
  "CUSTOMER_ID_2": {"choice": "new", "name": "Acme"},
  "CUSTOMER_ID_3": {"choice": "skip"}
}
```

- **`client`** puts the customer's invoices on a client you already have.
- **`new`** makes a client with the name you give.
- **`skip`** leaves the customer out.

Customers the file doesn't name are handled the default way.

## Run it

```sh
sudo -u chronoslice env CHRONOSLICE_DB=sqlite:///var/lib/chronoslice/chronoslice.db \
  SQUARE_ACCESS_TOKEN="$SQUARE_ACCESS_TOKEN" chronoslice import square --continue-numbering
```

Other options:

| Option | What it does |
|---|---|
| `--org <id>` | The organization to import into. The default is the only one. |
| `--continue-numbering` | Continue ChronoSlice's invoice numbers after Square's highest plain number, so `000653` is followed by `000654`. |
| `--skip 000123,000124` | Invoice numbers to leave in Square. |
| `--mapping <file>` | The mapping file above. |
| `--save <folder>` | Save what was read from Square to a folder, for a later `--from`. |
| `--from <folder>` | Read a saved export instead of calling Square. The folder holds `customers.json`, `invoices.json`, `orders.json` and `payments.json`. No token is needed. |
| `--dry-run` | Show what would happen without keeping anything. |

Running it again is safe. Invoices already imported only have their status and payments brought up to date.

## Turn on recurring invoices

Every recurring invoice comes in paused. For each one:

1. Cancel the series in Square.
2. In ChronoSlice, open **Invoices**, then **Recurring**, check the invoice, and turn off **Paused**.

Do it in that order, so nobody is billed by both. See [Recurring invoices](https://chronoslice.app/docs/using-chronoslice/recurring-invoices).

## Invoice attachments

If you've downloaded the files attached to your Square invoices into a folder that holds a `manifest.json` and a `files` folder, you can attach each one to the invoice it came with, after the main import:

```sh
sudo -u chronoslice env CHRONOSLICE_DB=sqlite:///var/lib/chronoslice/chronoslice.db \
  chronoslice import square-attachments --from ~/square-attachments --dry-run
```

Drop `--dry-run` to do it for real. Add `--org <id>` if there's more than one organization. Each file's size and MD5 are checked against the manifest first, and a mismatch is refused. Running it again adds nothing twice. It prints how many files were attached, how many were already there, how many belong to Square invoices that aren't in ChronoSlice, and any errors. It exits with status 1 when there were errors.

## After the import

- Look over your clients under **Clients**, and fix any names or addresses.
- Check **Invoices**, then **Settings**, for your numbering, payment terms and default notes. See [Invoices](https://chronoslice.app/docs/using-chronoslice/invoices).
- Connect Stripe if clients will pay online. See [Getting paid with Stripe](https://chronoslice.app/docs/using-chronoslice/getting-paid-with-stripe).

## Related

- [Command reference](https://chronoslice.app/docs/help/command-reference)
- [Recurring invoices](https://chronoslice.app/docs/using-chronoslice/recurring-invoices)
- [Settings reference](https://chronoslice.app/docs/installing/settings-reference)
- [What ChronoSlice is](https://chronoslice.app/docs/getting-started/what-is-chronoslice)

## Still stuck?

Send us a request: it goes to the people who build ChronoSlice, and the reply comes by email. Include your ChronoSlice version (Settings › Licence shows it) and what you tried.

 [Contact support](https://chronoslice.app/help/new?from=%2Fdocs%2Fmoving-to-chronoslice%2Ffrom-square)[Your requests](https://chronoslice.app/help/tickets)

---

## Navigation

- Parent: [Moving to ChronoSlice](https://chronoslice.app/docs/moving-to-chronoslice.md)
- Previous: [From Toggl Track](https://chronoslice.app/docs/moving-to-chronoslice/from-toggl-track.md)
