Finances API v0 Use Case Guide

You can use the Finances API v0 to obtain financial information relevant to a seller's business. You can obtain financial events for a given order, financial event group, or date range without having to wait until a statement period closes. For details about API operations and associated data types and schemas, refer to the Finances API v0 Reference.

Key features

• Retrieve your current balance: The Finances v0 API accepts GET operations to return the total balance of transactions within of open financial event groups.
• Check the balance and status of a fund transfer: The Finances v0 API accepts GET operations to return details about the status and balance of closed financial events that have successfully processed payments.
• Retrieve the transactions that make up a balance: The Finances v0 API accepts GET operations to look up the transaction trace identifiers, the total disbursement or charge amount, and the date and time of transactions.

Prerequisites

To successfully complete these tutorials, you must have:

• Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API applications.
• Approval for the Finance and Accounting role in your developer profile.
• The Finance and Accounting role selected in the app registration page for your application.

Tutorial: Retrieve your current balance

This tutorial demonstrates how to retrieve your open balance.

Step 1. Retrieve the current open balance

Call the listFinancialEventGroups operation to retrieve the latest 100 financial event groups and a page token that can be used to get the next set of financial event groups available.

Step 2. Filter for open financial event groups

Select the financial event groups where ProcessingStatus is equal to Open.

Step 3. Find the current balance

The OriginalTotal property provides the total amount of disbursement or charge in the currency of the marketplace in which the transactions occurred. CurrencyAmount provides the monetary value, while CurrencyCode provides the three-digit currency code in ISO 4217 format.

Tutorial: Retrieve the amount and status of a payment

This tutorial demonstrates how to retrieve the amount and status of a specific payment.

Step 1. Find the specific financial event group of the payment

Retrieve the latest 100 financial event groups and a page token that can be used to call next set of financial event groups available by calling the listFinancialEventGroups operation.

Step 2. Filter for closed financial event groups

To select financial groups that have successfully sent payments, select the financial event groups where ProcessingStatus is equal to Open.

Step 3. Retrieve the payment amount

The OriginalTotal property provides the total amount of disbursement or charge. CurrencyAmount provides the monetary value, while CurrencyCode provides the three-digit currency code in ISO 4217 format.

Tutorial: Retrieve the financial events that make up a financial event group

This tutorial demonstrates how to retrieve financial events that make up the financial groups that you identified in the preceding tutorials.

List financial events within a range of dates

Call the listFinancialEvents operation with the PostedBefore and PostedAfter query parameters.

List financial events by group ID

Call the ListFinancialEventsByGroupId operation with the eventGroupId path parameter. The response provides the first 100 financial events present in the financial event group and a page token that can be used to call next set of financial events.