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 withfinances: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:ACCESS_TOKEN and LINKED_ACCOUNT_ID in .env. Run the report with the first date of the week, in UTC:
> 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:
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 withclient.access.finances.earnings.timeseries.get():
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: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 acceptstartDate, 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.