A frequent pain point when setting up the Recurly → QuickBooks Online (QBO) integration is confusion around the Start Date and what will (and will not) sync during the first run. Merchants often expect the Start Date to:
- limit which customer accounts sync,
- backfill all historical invoices automatically, or
- prevent any “duplicate” issues when connecting to an existing QBO company.
This article explains the actual sync behavior, how to avoid common first-sync pitfalls, and the safest options for backfilling historical data.
How the Start Date works (and what it does not do)
What the Start Date does
When you configure the QBO integration, you set a Start Date. After setup, the integration runs on a schedule and syncs records that were created or updated after the Start Date (and since the last run).
What the Start Date does not do
- It does not prevent accounts from syncing. Recurly accounts generally sync regardless of Start Date so QBO has the needed customer records to reference invoices and transactions.
- It does not automatically “import all history” if you set it far in the past. Practical backfilling still depends on what exists in QBO already and whether duplicates will be triggered.
- It does not make QBO a source of truth. This is a one-way sync from Recurly to QBO; changes made in QBO do not sync back into Recurly.
First sync checklist (to avoid duplication + surprises)
- Use a fresh QBO company when possible.
If you connect Recurly to an existing QBO company with historical customers/items, you increase the likelihood of duplicate name / duplicate item issues. - Confirm QBO settings that commonly cause invoice sync errors.
Recurly generally recommends disabling QBO “Custom Transaction Numbers” to avoid invoice numbering conflicts. - Make naming choices intentionally.
- Customer Display Name must be unique in QBO. Pick a strategy that will remain unique at scale (many B2C merchants choose Account Code).
- Ensure plan/item/add-on names are unique and stay under QBO’s item name length constraints to avoid truncation-based collisions.
- Avoid deleting financial objects already synced.
Deleting credits, plans, or add-ons after they’ve synced can lead to errors that may require manual cleanup in QBO.
Backfilling historical data: what’s possible
Backfilling means getting older invoices/transactions into QBO after you connect the integration. There are two common, safe approaches:
Option A (Recommended): Start clean and let Recurly be the system of record
- Connect to a fresh QBO company.
- Set the Start Date to the earliest point you want QBO populated from Recurly.
- Let Recurly sync forward (and, depending on configuration + uniqueness, it can pick up older records after Start Date).
This approach reduces time spent resolving duplicates and mismatched objects.
Option B: Keep an existing QBO company and selectively backfill
- Expect to resolve duplicates (customers and items are the most common). Use Recurly’s “Resolve Error” workflow to link to the existing QBO customer/item when prompted.
- For older data that cannot be safely synced (or would create a large volume of conflicts), consider:
- importing summaries/journal entries into QBO, or
- manually recreating a limited set of invoices/credit memos needed for reporting continuity.
Forcing an extra run / catching up quickly
If you’ve fixed configuration or resolved duplicates and want the integration to try again sooner, use the Queue sync action from the QBO integration page to trigger an on-demand sync.
Common scenarios & recommended approach
| Scenario | What’s happening | Recommended approach |
|---|---|---|
| “I set the Start Date to last year, but all my customers are syncing.” | Accounts sync to ensure invoices/transactions have a valid customer reference in QBO. | This is expected behavior. Focus on uniqueness of Display Name and resolve any duplicate customer errors. |
| “We connected to an existing QBO company and now have lots of duplicate errors.” | QBO requires unique names for customers and items; historical QBO data often conflicts with Recurly objects. | Use “Resolve Error” to link to existing QBO records. If conflicts are widespread, consider moving to a fresh QBO instance. |
| “Old invoices aren’t in QBO and we need them for reporting.” | Backfilling can be limited by existing QBO objects and conflicts. | Decide whether to (A) connect to a clean QBO company and backfill from Recurly, or (B) keep QBO and backfill selectively (journal entries / manual invoices). |
| “Invoices won’t sync due to numbering conflicts.” | QBO settings like Custom Transaction Numbers can cause invoice sync issues. | Disable Custom Transaction Numbers in QBO (recommended), then queue a sync. |
| “We deleted a plan/add-on and recreated it, and now QBO shows duplicates.” | Previously synced objects can’t be reused cleanly; recreation may trigger duplicate object errors. | Stop and contact Support. Avoid recreating with the same codes; link where possible and plan cleanup carefully. |
Troubleshooting
Duplicate customer / duplicate item errors
- These are among the most common QBO sync errors. If QBO already has a customer/item with the same unique name, Recurly will surface the error and provide a Resolve Error workflow to link to the matching QBO record.
- If you see frequent duplicates, re-evaluate:
- Customer Display Name mapping (Account Code is usually the most reliably unique)
- Plan/item/add-on naming strategy (avoid long names that might be truncated)
Closed accounting period errors
If QBO rejects updates because the accounting period is closed, you can either reopen the period in QBO or ignore the sync error in Recurly and handle the accounting entry directly in QBO (depending on your accounting controls).
Comments
0 comments
Please sign in to leave a comment.