Import hours and projects from ClickUp into SamBooks

Connect ClickUp once, pick a date range, and SamBooks pulls in the hours your team tracked. Imported entries become timesheets ready to invoice, with no double data entry. Rates and project value stay administrative data you set in SamBooks.

What it is for

If your team tracks time in ClickUp, this integration closes the gap ClickUp leaves open: turning tracked hours into an electronic invoice. SamBooks imports the billable slice of the work (hours, projects, activities, team members, the billable flag) and feeds it into timesheets, where it follows the same invoicing flow as manually entered hours.

The sync runs one way only, from ClickUp into SamBooks. ClickUp stays the tool where you organise your team's work; SamBooks becomes the tool where that work turns into invoices. SamBooks never writes back to ClickUp and does not replace ClickUp for project management.

Requirements

• A ClickUp account with access to the workspace whose hours you want to import.
• The Gestore (Manager) or Amministrativo (Administrative) role in SamBooks: only these roles can connect a tool, import and reconcile. Collaborators do not see these controls.
• For the token connection: a ClickUp personal token starting with pk_. You will find it in your ClickUp profile settings.

Step-by-step

1. Open the PM Integrations tab

Go to Progetti (Projects) and open the Integrazioni PM (PM Integrations) tab. You will see two connection cards (ClickUp and CSV/Excel file) and, below them, the Reconciliation section.

2. Connect ClickUp

You have two equivalent options.

• Connect with ClickUp (recommended): opens the ClickUp consent page where you authorise SamBooks to access your workspace. When you are done you return to SamBooks automatically and the ClickUp card shows as connected.
• Connect with the token: paste your ClickUp personal token (pk_…) into the field and press Connect with the token. SamBooks validates the token live with ClickUp and selects the workspace. If the token is invalid or grants no workspace access, you get a message and nothing is saved.

In both cases the token is stored encrypted on the SamBooks side. The ClickUp card then shows the Connected label, the workspace and the last sync time.

3. Import hours for a date range

With ClickUp connected, optionally set From and To with the date pickers and press Import now. If you leave the range empty, SamBooks imports the last 30 days. When it finishes you see a summary: how many timesheets were created and how many items remain to reconcile.

Alternatively, from the CSV/Excel file card you can upload an hours sheet exported from any tool. The expected columns are Date, Hours, Collaborator, Project, Activity, Billable, Rate, Description; rows that cannot be parsed are skipped with a reason, without failing the whole import.

4. Reconcile client and resource

Right after the import, the Reconciliation section lists the items to match, with the pending ones first. For each one SamBooks shows the external label (for example "ClickUp: Acme S.r.l.") and a select to choose the matching SamBooks client or resource, then you press Confirm.

• Automatic matching happens only when the name matches exactly and uniquely, so no wrong matches are created. Everything else is a manual choice.
• The project → client link is the main one to confirm by hand, because ClickUp has no concept of a client.
• Choosing a resource does more than label it: SamBooks actually moves the imported timesheets onto the SamBooks resource you select, so the project's costs and totals stay correct.
• Projects and activities already matched one-to-one appear under Already linked, read-only.

When nothing is left to reconcile you see the message confirming the imported timesheets are ready to invoice.

5. Generate the invoice

Once the project has a confirmed client, from the project detail you use Generate T&M invoice: SamBooks gathers the billable, not-yet-invoiced hours, aggregates them by client and period, and produces an electronic TD01 invoice draft. It is the same flow as manually entered hours. Until a project's client is confirmed, the project cannot be invoiced: this is a safeguard against invoice drafts with wrong data.

What SamBooks imports from ClickUp (and what it does not)

SamBooks imports:

• Projects, from ClickUp Lists.
• Activities, from ClickUp Tasks.
• Resources, from workspace members.
• Hours (timesheets), from ClickUp time entries, with each entry's date and billable flag. Timers still running are not imported.

SamBooks does not import from ClickUp:

• The client: ClickUp has no native client entity. You match the client in SamBooks during reconciliation.
• The rate and the project value: these are administrative data you set only in SamBooks, in the project price list. As the tab itself states: for ClickUp you set the rate in SamBooks (from the project price list); ClickUp exposes neither rates nor clients.

There is one optional exception, off by default: if your ClickUp uses custom fields for client or rate, SamBooks can read them and propose them during the import. This is an advanced setting and does not replace the price list.

Tips

• Import in manageable ranges (one month at a time) to keep reconciliation tidy.
• Reconcile clients right after the first import: without a client, the project stays non-billable.
• Re-importing the same range does not duplicate already imported hours: SamBooks recognises each entry and skips the ones already present.
• If you prefer, you can ask Sam in chat how the last ClickUp import went or how many reconciliations are pending.

Common errors

• "Invalid ClickUp token or no workspace." The personal token is wrong or grants no workspace access. Check you copied the full pk_… token from ClickUp settings.
• Skipped rows after a CSV import. Some sheet rows could not be parsed (missing or invalid date or hours, empty collaborator or project). The summary tells you how many rows were skipped; fix the sheet and re-import.
• The project will not invoice. A confirmed client is missing: open it in the Reconciliation section, match the client and press Confirm.
• Missing hours after the import. ClickUp returns only the connected user's hours by default; SamBooks fetches them for every workspace member. If hours are still missing, check the selected range and that the entries are not timers still running.

FAQ

Does SamBooks write anything to ClickUp? No. The integration is inbound only: ClickUp stays untouched.

Do I have to re-enter rates every time? No. Rates live in the project price list in SamBooks and apply automatically to imported hours when you invoice.

What happens if I import the same range twice? Nothing problematic: already present hours are not duplicated and what was already invoiced is not invoiced again.

Can I use ClickUp and Excel sheets together? Yes. You can have ClickUp connected and also upload CSV/Excel sheets; reconciliation handles both sources.

Who can connect and import? Only the Manager and Administrative roles. Collaborators see their own hours but not the integration controls.

Related features

• Managing projects: how to structure projects, activities and the price list in SamBooks.
• Project timesheets and invoicing: how hours are reviewed and the T&M invoice is generated.