Best Practices

Recommended setup

Match credentials to environment

Always confirm whether you need Sandbox or Production credentials before setting up. Mixing them is the most common source of empty or incorrect exports.

Start with Transactions

Transactions is the richest and most frequently queried entity. Get it flowing first, then layer in Subscriptions and Disputes as separate entities in the same data flow.

Join Subscriptions to Plans

Use Coupler.io's Join transformation on `plan_id` to enrich your subscription records with plan name, price, and billing frequency — useful for MRR breakdowns by tier.

Join Disputes to Transactions

Link disputes back to transactions using `transaction_id` to calculate your chargeback rate by payment method, merchant account, or date range.

Data refresh and scheduling

Daily refresh for Transactions and Disputes

Transaction status changes (e.g., authorized → settled → disputed) happen throughout the day. A daily refresh keeps your revenue and risk numbers current.

Weekly is enough for Plans and Discounts

These entities change infrequently. A weekly or even manual refresh is sufficient unless you're actively rolling out new pricing or promotions.

Performance optimization

Set a meaningful start date

The start date directly controls how many transaction records are fetched. For ongoing reporting, set it to 90 days or less — pull your full history separately in a one-time data flow.

Use Aggregate for revenue summaries

Rather than loading every transaction into a spreadsheet and summing there, use Coupler.io's Aggregate transformation to pre-group by day or month. This keeps destination files lean and fast.

Common pitfalls

Don't report on raw transaction totals without filtering by status. Including failed, voided, or authorized-but-not-settled transactions will inflate revenue figures. Always filter to status = settled for accurate revenue reporting.

Do

• Filter transactions by status = settled for revenue reports
• Use separate data flows for Sandbox vs. Production
• Join Disputes to Transactions to calculate chargeback rates
• Use Append to combine data from multiple merchant accounts

Don't

• Mix Sandbox and Production credentials in the same data flow
• Set the start date to your company's founding date for routine refreshes
• Assume refunds appear as negative amounts on original transactions
• Report subscription counts without filtering by status