From Square
Import customers, invoices with their payments and fees, and recurring invoices from Square, without billing anyone twice.
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 and 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:
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:
{
"CUSTOMER_ID_1": {"choice": "client", "client_id": "A ChronoSlice client id"},
"CUSTOMER_ID_2": {"choice": "new", "name": "Acme"},
"CUSTOMER_ID_3": {"choice": "skip"}
}
clientputs the customer's invoices on a client you already have.newmakes a client with the name you give.skipleaves the customer out.
Customers the file doesn't name are handled the default way.
Run it
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:
- Cancel the series in Square.
- 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.
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:
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.
- Connect Stripe if clients will pay online. See Getting paid with Stripe.
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.