Cubby Storage Integration: Setup and Sync

Connect Cubby Storage to DualEntry to pull self-storage operational data - facilities, units, customers, payments, leases, and more - and import it as journal entries in your ledger. The integration runs in either cash-based mode (general-ledger cash report lines) or accrual-based mode (ledger entries); the two modes are mutually exclusive per integration. Data flows one way: Cubby → DualEntry. DualEntry never writes back to Cubby.

Prerequisites

Confirm the following before connecting:

A Cubby Storage API key with permission to call the endpoints DualEntry uses: organizations search, facilities, units, customers, payments, access codes, ledgers, leases, notes, and the cash GL report (when running in cash-based mode).
A DualEntry company assigned to the integration. The integration list filters on integrations that have a company set, so an integration without a company won’t surface in the UI.
Your chart of accounts configured in DualEntry. After the initial sync, DualEntry creates account records derived from Cubby data that you map to your GL accounts.
A decision on whether to use cash-based or accrual-based accounting before the first sync - the choice changes which Cubby endpoints DualEntry pulls.

Choose cash-based or accrual-based mode

Cubby exposes accounting activity in two distinct shapes, and DualEntry supports either but not both at once for the same integration. Pick the mode before connecting; switching later requires a resync and may produce duplicate or out-of-order journal entries until the historical data is reconciled.

Cash-based mode pulls Cubby’s general-ledger cash report. DualEntry creates journal entries that reflect cash movements only - payments received, refunds, transfers - and ignores accrual-side activity like charges and write-offs.
Accrual-based mode pulls Cubby’s ledger entries. DualEntry creates journal entries for charges, payments, write-offs, and transfers, matching Cubby’s accrual ledger. Use this mode if you reconcile against Cubby’s accrual books rather than its cash report.

The mode is enforced at integration setup: if a single integration ever ends up with both cash and accrual sync methods enabled, DualEntry raises a duplicate-sync-methods error and refuses to run rather than write conflicting entries.

How to connect

The integration uses a Bearer token - the Cubby API key - for authentication. You provide the key in DualEntry; DualEntry stores it encrypted and sends it on every request to Cubby as Authorization: Bearer <api_key>.

In DualEntry, navigate to Settings → Integrations → Cubby Storage.
Provide your Cubby Storage API key.
Set a DualEntry company on the integration so it’s scoped to a single entity (required to complete setup - see Prerequisites).
Choose Save. DualEntry queues the initial sync: authenticate, then pre-setup - discover the Cubby organization, sync facilities and companies, pull cash reports or ledger entries depending on the chosen mode, then sync the account records derived from that data.
In the integration’s mapping screens, map every Cubby facility and Cubby company to its DualEntry counterpart, and map every account (including at least one payment-method account - the GL account where Cubby payments post, such as an Undeposited Funds or bank-clearing account).
Choose Validate to confirm credentials and readiness. DualEntry checks that the integration is connected, every required mapping is filled in, and the integration has a company assigned. A successful validation returns a confirmation; an incomplete one tells you which mapping is still missing.

What syncs

Each sync run pulls the following Cubby data into DualEntry:

Cubby data	DualEntry record	Notes
Organizations	implicit context	Used as the parent for all other syncs. The organization ID is taken from existing integration records when present, otherwise from the first result of Cubby’s organization search.
Facilities	mapping	Each Cubby facility must be mapped to a DualEntry counterpart before setup is complete.
Companies	mapping	Each Cubby company must be mapped to a DualEntry company.
Units, customers, leases, access codes, notes	reference data	Pulled for context; not posted directly as accounting records.
Payments	reference data	Reflected on cash reports or ledger entries depending on mode.
Cash reports (cash-based mode only)	`journal_entry`	One journal entry per cash report line.
Ledger entries (accrual-based mode only)	`journal_entry`	One journal entry per ledger entry - charges, payments, write-offs, transfers.
Accounts (Cubby-derived)	mapping → DualEntry GL account	DualEntry creates an account record per distinct account it sees in Cubby’s data; you map each one to a real GL account before sync produces journal entries.

Cubby’s cash and ledger histories can extend years back. To bound the import window, configure the cash-report start date (cash-based mode) or the ledger-entry start date (accrual-based mode) so DualEntry only pulls data on or after that date.

How sync runs

Once setup is complete, sync runs continue automatically. A few behaviors to know about:

Sync only runs when the integration status is Connected. Disconnected or pending integrations are skipped.
Listing the integration in the UI may enqueue a sync when appropriate (for example, a first-time backfill).
Cubby provider calls retry up to three times on transient HTTP errors before surfacing the failure.
If the API key returns multiple Cubby organizations, the integration uses the first result by default and logs a warning. If you need a specific organization, ensure it appears first in Cubby’s response, or contact DualEntry support to seed the correct organization ID on the integration.

Troubleshoot sync errors

When a record fails to sync or validation fails, the most common causes:

Symptom	Cause	Resolution
`401` / auth failures	Invalid or revoked Cubby API key.	Regenerate the key in Cubby and update the integration credentials in DualEntry.
Validate returns “setup incomplete”	Unmapped facilities, companies, or accounts; or no DualEntry company assigned to the integration.	Map every facility and Cubby company; map all required accounts including at least one payment-method account; confirm the integration has a DualEntry company.
No organizations / empty sync	Cubby returned no organizations, or the organization context failed validation.	Confirm the API key’s scope. If multiple Cubby organizations exist, ensure the correct one is represented in integration records (the first organization from search is used by default).
Accrual data missing	The integration is in cash-based mode.	Switch to accrual-based mode and resync. Existing journal entries from cash mode remain - review for duplicates before reposting.
Cash report lines missing	The integration is in accrual-based mode, or the cash-report start date excludes the data.	Confirm the integration mode and the cash-report start date setting.
Duplicate-sync-methods error	The integration has both cash and accrual sync methods enabled.	Pick one mode. The configuration only supports one at a time.
Transient HTTP errors after retry	Network issue or Cubby availability.	The provider already retries three times; resync after the outage clears.

FAQ

Does DualEntry write back to Cubby?

No. The integration is pull-only. Cubby remains the system of record for operational data; DualEntry only mirrors the accounting impact.

Can I use both cash reports and ledger entries on the same integration?

No. The two modes are mutually exclusive - they describe the same activity from different viewpoints, so combining them would produce duplicate journal entries. The integration enforces this at setup and refuses to run if both are enabled.

What if my Cubby account spans multiple organizations?

The integration uses the first organization returned by Cubby’s organization search and logs a warning if more than one exists. Multi-organization scoping isn’t currently a self-service setting; contact DualEntry support to seed a specific organization ID on the integration.

For maintainers

The details below describe deployment and connector configuration, not user-facing features.

API host: CUBBY_STORAGE_BASE_URL (production) or CUBBY_STORAGE_SANDBOX_BASE_URL (sandbox), selected by environment in provider.py.
Mode setting key: CUBBY_STORAGE_INTEGRATION_TYPE, with values cash_based or accrual_based (CubbyIntegrationType enum in cubby_sync_service.py).
Date-window setting keys: CUBBY_STORAGE_CASH_REPORT_START_DATE and CUBBY_STORAGE_LEDGER_ENTRY_START_DATE.
Internal validate endpoint: POST /api/integrations/cubby/{integration_id}/validate/ invokes CubbyStorageSyncService.validate(). Returns 200 with a success message when valid; 424 when setup is incomplete or validation fails.
Sync lock: scheduled syncs run through sync_with_lock, which short-circuits unless the integration status is CONNECTED.
Ledger entry processing dispatches by LedgerEntryType - CHARGE, PAYMENT, WRITE_OFF, TRANSFER - each with its own handler in cubby_sync_service.py.

Result

After completing these steps, you have a Cubby Storage integration that pulls organization, facility, and accounting data and posts it to DualEntry as journal entries in either cash-based or accrual-based form. Cubby remains the system of record for operational data; DualEntry holds the accounting view. To compare other pull-only integrations, see Bill.com and Ramp. To audit the resulting entries, see Journal Entries. To connect additional systems, return to Integrations.

Documentation Index

​Cubby Storage Integration: Setup and Sync

​Prerequisites

​Choose cash-based or accrual-based mode

​How to connect

​What syncs

​How sync runs

​Troubleshoot sync errors

​FAQ

​Does DualEntry write back to Cubby?

​Can I use both cash reports and ledger entries on the same integration?

​What if my Cubby account spans multiple organizations?

​For maintainers

​Result