> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dualentry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cubby Storage Integration: Setup and Sync

> Connect Cubby Storage to DualEntry to import facility activity as journal entries in cash-based or accrual-based mode, configurable per integration.

Connect [Cubby Storage](https://www.cubbystorage.com/blog/cubby-partners-with-dualentry) to DualEntry to pull self-storage operational data - facilities, units, customers, payments, leases, and more - and import it as [journal entries](../core-financials/general-ledger/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](../core-financials/general-ledger/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>`.

1. In DualEntry, navigate to **Settings → Integrations → Cubby Storage**.
2. Provide your Cubby Storage API key.
3. Set a DualEntry company on the integration so it's scoped to a single entity (required to complete setup - see Prerequisites).
4. 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.
5. 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).
6. 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](./bill-com) and [Ramp](./ramp). To audit the resulting entries, see [Journal Entries](../core-financials/general-ledger/journal-entries). To connect additional systems, return to [Integrations](./index).