How-to guideCarbon Measurement

Backfill transaction history after user consent

Upload a consenting user's full transaction history in batches, then poll until the processing flag is false to know when their dashboard is ready.

Some programmes only share a user's transactions once that user has opted in. You collect and manage that consent within your own application — Connect Earth never collects it and holds no data for the user until you upload it. When the user activates the experience, your back end uploads their transaction history (typically twelve months) and polls until processing completes, then renders their dashboard. This builds on asynchronous integration.

How it works

Backfill a user's history

1. Collect consent in your application. Only gather and upload the user's transactions once they have opted in. If you're personalising results, this is also a natural moment to present the user habits questionnaire and submit the answers to POST /questionnaire.
2. Gather the user's history. Twelve months of transactions gives enough data for meaningful trends and month-on-month insights.
3. Upload in batches. Send the history to POST /transaction/bulk/upload in batches of up to 250 transactions, each with a transaction ID. Large uploads are queued for processing rather than processed inline.
4. Poll until processing completes. The aggregate endpoints — such as POST /monthly-insights/totals — return a processing field alongside the results. While it is true, uploaded transactions are still being processed and the results are incomplete; once it is false, processing has finished and you can use the results with certainty. The response also includes a transaction_count, which you can compare against the number you uploaded to drive a percentage-complete indicator on the loading screen while you wait.
5. Fetch and render. Request the insights the dashboard needs — monthly totals and breakdowns, tips and recommendations — and render the user's full history. The UI/UX best practices guide covers making the first-load experience feel worth the wait.

How long it takes

Processing time is proportional to the number of transactions, at roughly one millisecond per transaction — a user with 5,000 transactions in their twelve-month history is fully processed in around five seconds. The loading screen and progress indicator only need to hold the user's attention for a moment.

For request and response schemas, see the Carbon Measurement API reference.

See also

For a large backfill spanning many users at once, rather than one new user's history, see Backfill transactions across users.