Skip to main content

​
What Gmail Sync does

Gmail Sync searches a connected Gmail account for likely dispensary receipts, lets you choose candidate emails, and turns each confirmed receipt into its own order. Historical Import also requests one notebook for every confirmed historical order. Quick Sync follows the normal Gmail access policy; Historical Import is a separately flagged, one-time archive purchase. Both use Google’s read-only gmail.readonly permission.
The complete implemented flow is maintained in Order Activation. That page is the source of truth when this guide and older planning material disagree.

​
Before you start

For the most accurate search, save the dispensary where you shop and associate a receipt email domain with it. A shop is Quick Sync-ready only when it has at least one emailDomains value. The Add/Edit Shop form and Gmail’s inline shop setup both manage confirmed receipt domains. Contact email and website can suggest a domain, but Gmail does not search it until the user confirms it.

​
Connect Gmail

1

Open Add Order

Open the order-upload hub and choose Gmail Sync.
2

Connect or reauthorize Google

High IQ opens Google’s OAuth flow and requests read-only Gmail access. A Google sign-in by itself does not include this permission.
3

Confirm the connection

After Google returns to the app, Clerk refreshes the account scopes and Convex verifies the Google connection server-side before enabling scans.
High IQ cannot send, modify, or delete email. OAuth tokens are retrieved server-to-server and are not exposed to the mobile app.

​
Historical import

Historical discovery supports up to 2,000 candidate receipts per import. That is a configurable global scan cap, not a per-shop or per-query allowance. You can complete the free discovery and preview before the one-time purchase is required.
1

Choose a date range

The default is the largest configured archive range, currently Up to the past 10 years. You can narrow it to 6 months, 12 months, 2 years, 3 years, or a custom range. The archive horizon is configurable up to 22 years.
2

Start the scan

Choose one or more Gmail-ready saved shops for a targeted domain scan. A broader community and keyword search is available only as an explicit secondary option.
3

Review dispensary groups

Turn groups on or off. This controls which candidate emails continue. Validated sender domains are attached to the linked shop only after the resulting order is reviewed and confirmed.
4

Review candidate emails

Inspect sender, subject, date, snippet, classification confidence, and the estimated summary. Candidates are loaded in pages so large archives remain responsive. Select only messages you want imported.
5

Unlock and parse the archive

After the free preview, restore an existing entitlement or complete the one-time Historical Import purchase. High IQ then fetches and parses the selected email bodies in bounded background chunks. Each successful parse becomes a staged review, not an order.
6

Review each parsed receipt

Correct the shop, date, total, names, matches, quantities, units, prices, selection, and unknown-strain confirmations. Save it or explicitly skip it. Duplicates, no-item results, and failures are reported separately.
7

Confirm safe orders faster

Fully resolved, high-confidence receipts can be confirmed in safe bounded groups. Anything incomplete, ambiguous, or unmatched stays in the individual editable review queue.
8

Explore the archive

Every confirmed receipt becomes an individual order and requests its own notebook. Open Stash → Orders to search, filter, and inspect the complete purchase archive while notebook and strain research work continues.
A Gmail candidate is never an order by itself. totalImported increments only after the staged receipt has passed Review & Confirm and committed.

​
Quick Sync

Quick Sync is for returning users. It displays saved shops, preselects the most recent Quick Sync-ready shop, and searches the selected domains.
1

Choose shops

Select one or more shops with receipt email domains. Shops marked Needs domain cannot be selected for Quick Sync.
2

Sync the last seven days

High IQ uses Gmail History when a valid cursor exists. If no cursor exists or it expired, the backend uses a bounded fallback without silently skipping unprocessed history.
3

Review new candidates

Select the candidate emails you want. Found candidates are not counted as imported orders.
4

Import selected orders

The same batch parser and idempotent order writer used by historical import processes the selected messages.
If no candidates are found, try another saved shop, use Advanced Options for a broader historical scan, or use text input.

​
What happens after import

Gmail imports use addToStash: false; importing purchase history never changes active inventory automatically. Historical Import requests a notebook for every committed order. From order detail, users can still add eligible resolved items to Stash or manage notebook state when policy allows it.

​
Resume, retry, and cancel

  • Leaving the app does not abandon the archive. Reopening Historical Import or tapping the active-import banner in Orders restores the current job.
  • Trigger runs, message outcomes, and order commits use stable idempotency. An automatic continuation or retry does not replay successful receipts.
  • Resume Import appears on recoverable historical errors. It safely reschedules the stored scan or import attempt, or returns directly to review when parsing already finished. Retry Failed selects failed messages only.
  • Cancel Import terminalizes the job, discards its pending review drafts, and attempts to cancel known scan/import runs. If provider cancellation is incomplete, the app reports that truthfully and late writes remain blocked.

​
Duplicate and counter guarantees

  • One Gmail message ID can create at most one order per user.
  • Repeated callbacks and retries are idempotent.
  • totalImported counts newly successful orders only, not candidates, duplicates, no-item results, or failures.
  • Incremental history cursors do not advance across an incomplete bounded discovery window.

​
Privacy and disconnect

Disconnecting Gmail first closes local write boundaries and invalidates the connection generation so late callbacks cannot write. High IQ then attempts to cancel known background runs and revoke the delegated Gmail token. Imported orders remain in the account.

​
Current limitations

  • Photo and image receipt parsing is outside this flow.
  • Changing a saved order’s strain identity after commit requires adding a corrected order so matching, confirmation, research, and Stash effects can run through one trustworthy boundary again.

Order Activation

Full implemented flow, including strain confirmation and durable save.

Manage Shops

Understand shop fields and Gmail readiness.

Sync Troubleshooting

Recover from connection, scan, and import failures.

Gmail Architecture

Technical system boundaries and durable job states.