Skip to main content
Create a weekly report that shows earnings over time and totals by payment type and status. Save the payment records so you can check what makes up each total.

Choose your report

Use earnings data to see changes over time. Use transactions to see individual payments. Content and marketing analytics show how posts and campaigns perform. The report below includes earnings and transactions, with separate totals for each. Use the weekly report example on GitHub. It uses Node.js 22 or later and calls the HTTP API to read data.

Before you start

Ask the user to authorize your app with finances:read, which lets your app read financial data. Select a linked account. On your server, set ACCESS_TOKEN and LINKED_ACCOUNT_ID to the returned values. Create a client to use the TypeScript SDK release candidate.

Build a weekly report

Clone the example and copy its settings template:
Set ACCESS_TOKEN and LINKED_ACCOUNT_ID in .env. Run the report with the first date of the week, in UTC:
The report covers October 5 through October 11, inclusive. The > in the command saves the report to weekly-report.json. The program saves the payment records to weekly-transactions.json. Each run replaces both files, so use a separate directory for each report you want to retain. Both files contain financial data. For a week with two completed tips, a report can look like this:
Use byTypeAndStatus for the report’s payment breakdown and earnings.amountPoints for its trend. The report keeps each transaction’s status, including null. It includes all returned statuses. A transaction in this report is not proof that its funds are ready for payout.

Read earnings over time

The example reads the week’s earnings with client.access.finances.earnings.timeseries.get():
The response groups values by metric, such as total. It does not use items. This code reads the earnings trend:
chartAmount[].count is the money amount at that point. chartCount, when present, tracks counts instead of money. The metric can also include gross and delta. With monthlyTotal=true, the response can include monthly entries with date, net, and gross. Keep the returned dates and earnings total in your report. Do not add the earnings total to the transaction total. They can include different payments. To request older data, keep the same startDate and move endDate backward.

Read transactions

The SDK can read every transaction page for you:
This endpoint accepts startDate and no endDate. The program keeps records from the start of the week up to, but not including, the start of the next week. It uses createdAt in UTC. If page.hasMore is true, send page.nextCursor as the next request’s cursor. Keep startDate, limit, and all filters the same. The program reads every page and counts each id once. It stops with an error if the cursor repeats. Page order does not prove that all later records fall outside the week. amounts.gross, net, fee, vat, and tax are in US dollars: 12.50 means $12.50. The program adds each field in whole cents, then returns dollars. It stops if a payment uses another currency. The saved records include id, type, createdAt, amounts, currency, description, status, payoutPendingDays, and user. The user field can be null. To narrow the report, use a documented transaction type and, for type=tips, a tipsSource. Apply the same filters on every page. If you filter transactions, do not compare their total directly with earnings that have no matching filter.

Read chargebacks and payouts

Use chargeback records to review disputed payments. Use payout balances to check available funds. Keep these separate from earnings. Chargeback requests accept both a start and an end date, and return results in pages. Earnings transaction requests accept only a start date. Check the API reference before adding any amounts to your report.

Measure content performance

After publishing a post or story, use its saved ID to read its analytics. Top-content lists show the best-performing content. Engagement data shows changes over time. Compare the same date ranges. Check the required permission and returned fields in the API reference.

Measure marketing performance

Use tracking-link analytics to compare campaign links. For a mass-message campaign, save the queue ID from creation. Use mass-message analytics and the buyer list to check results. Sent mass-message analytics accept startDate, endDate, and cursor. Buyer lists accept limit and cursor. If a read fails, follow V3 error recovery and rerun the report after resolving the error. Use the report only after the program finishes without an error.