Capture structured purchase data automatically from users’ retailer accounts.
How It Works
Users connect their retailer accounts (Amazon, Walmart, Target, and others) through your app. Actual retrieves historical and ongoing orders and returns structured, item-level purchase data.
Account linking captures both online and in-store purchases tied to the user’s retailer account. This includes delivery, pickup, and in-store transactions depending on retailer coverage.
Because data is pulled directly from retailer order records, account linking typically provides the most complete and reliable purchase data of any capture channel.
What We Extract
- Merchant name and location
- Purchase date and time
- Subtotal, tax, and total
- Itemized products with prices, quantities, and descriptions
- Order type (in-store, delivery, pickup)
- Order number
- Payment method
- Delivery and pickup dates (when available)
See Data Reference for the complete list of fields.
How Users Connect
The SDK presents retailer login screens directly within your app.
Users:
- Select a retailer
- Sign in with their existing credentials
- Complete any two-factor authentication required by the retailer
Once connected:
- Historical orders are retrieved based on your configured lookback period
- New orders are collected automatically in the background
Key UX principles
- Credentials are encrypted and stored only on the user’s device
- Credentials are never sent to or stored on Actual’s servers
- Users can disconnect retailers at any time
- Expired sessions trigger re-authentication prompts
What Happens After Linking
Initial Sync
- Retrieves historical orders based on configured lookback
- Some retailers support up to 3 years of history
- Typically completes in 5–10 minutes depending on volume
For stability, some historical retrieval may be spread across multiple user sessions. Actual optimizes this per retailer.
Ongoing Order Collection
- New orders are collected automatically
- Typical sync time: 30 seconds to 2 minutes
- Can run in background with minimal battery impact
Session Management
Retailer sessions expire periodically depending on retailer security policies.
Your app should:
- Detect expiration
- Prompt users clearly to re-authenticate
- Explain why re-authentication is needed
Supported Retailers
Actual supports 50+ retailers across major categories.
| Category | Example Retailers |
|---|---|
| Online marketplaces | Amazon, Temu, AliExpress, Shein |
| Grocery delivery | Instacart, Shipt, Thrive Market |
| Mass retail | Walmart (in-store + online), Target |
| Club / warehouse | Costco, Sam’s Club, BJ’s |
| Home improvement | Home Depot, Lowe’s |
| Grocery & pharmacy | Meijer, Publix, Safeway, CVS, Walgreens |
For the full list, see Supported Retailers.
Coverage varies by retailer and order type (in-store, delivery, pickup). Your Actual account team can review specific coverage for priority merchants.
Implementation Options
Standard Integration
Use the pre-built account linking interface with minimal customization.
What you get
- Pre-built retailer login screens
- Standard error handling and user guidance
- Automatic background sync
- Customizable user messaging
Timeline: ~1 week plus QA/release cycle
Best for: Most implementations, MVPs, fast launches
Custom Integration
Full control over the account linking experience.
What you get
- Custom-designed login and account management UI
- Advanced background sync using OS-level processing and silent push
- Enhanced session management
- Dedicated support and SLA
Timeline: 1–2 additional weeks plus QA/release cycle
Best for: Enterprise-scale deployments or custom UX needs
Setup & Configuration
Account linking requires your SDK license key with digital features enabled.
Contact your account team or XXXif access needs to be added.
Configure:
Retailer coverage
Choose which retailers users can connect.
Historical lookback
Define how far back to retrieve orders (varies by retailer).
Background sync behavior
Standard background sync or advanced silent push integration.
User Experience
Onboarding
Strong onboarding is critical for adoption.
Clearly communicate:
- What data is collected
- Why it’s valuable
- That credentials stay on-device
- That users can disconnect anytime
Linking Flow
- User selects retailer
- SDK presents login screen
- User completes credentials and 2FA
- Initial sync begins
- User can link additional retailers
Ongoing Experience
Plan for:
- Sync status indicators
- Re-authentication prompts
- Linked retailer management screens
- Value reinforcement (orders captured, rewards earned, savings found)
Common Error Scenarios
| Scenario | User Sees | Recommended Handling |
|---|---|---|
| Invalid credentials | Login failed | Prompt retry |
| 2FA required | Verification screen | Guide through flow |
| Account locked | Temporary lockout | Explain and retry later |
| Retailer down | Unavailable | Notify and retry later |
| Session expired | Re-auth needed | Friendly re-login |
| Network issue | Connection error | Retry suggestion |
Performance
| Metric | Expectation |
|---|---|
| Account setup | 30 seconds – 2 minutes |
| Initial sync | 5–10 minutes |
| Ongoing sync | 30 seconds – 2 minutes |
| Background sync | Automatic, low battery impact |
Some historical order retrieval may be spread across multiple sessions for stability.
Key Metrics to Track
Adoption
- Linked accounts per user
- Completion rate
- Popular retailers
Health
- Authentication success rate
- Re-auth success rate
- Session duration
- Common errors
Value
- Orders per sync
- Orders per user over time
- Collection success rate
Privacy & Security
- On-device credential encryption
- No credential storage on servers
- TLS encryption in transit
- User-controlled disconnect
- Customer owns extracted data
- No credential reuse
Next Steps
- Confirm license access
- Select retailers to enable
- Configure lookback and background sync
- Hand off to engineering for implementation