Marketplace Payouts: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

List a partner's marketplace payouts for a period

Show a partner the marketplace transactions they earned revenue share on within a date range, such as a single month.

To list a partner's marketplace payouts for a period:

1. Call Query Marketplace Payouts with a filter on transactionDate and sort the results so the most recent payouts come first. Set cursorPaging.limit to 100 (the maximum). If you receive a full page, follow pagingMetadata.cursors.next to retrieve the next page.

   Copy

2. For each returned payout, read amount (in USD), transactionAmount, listing, and negative to present the earning. Payouts with negative set to true reverse an earlier earning, so subtract them when totaling.

3. To display a single total instead of a list, call Get Marketplace Payouts Aggregate with the same filter and read payoutsTotalAmount and payoutsCount. The total covers exactly the payouts the filter matches, including rejected ones.

4. To match the earnings total in the Wix Studio dashboard, which leaves rejected payouts out of the total while still listing them, add a status condition to the aggregate filter:

   Copy

   status isn't part of the query pattern declared for Query Marketplace Payouts, so you can't reuse this condition when listing payouts — filter by date there and skip rejected rows client-side.

Reconcile marketplace earnings against a monthly invoice

Confirm that the marketplace payouts a partner earned in a month match the marketplace sub-total of that month's invoice, and check whether the partner has been paid.

To reconcile marketplace earnings for a month:

1. Call Query Marketplace Payouts filtered to the month, as in the flow above, and sum the amount of the payouts whose status isn't REJECTED (keeping negative payouts in the sum, since they offset earlier earnings). Rejected payouts are never invoiced, so including them would overstate the total against the invoice. Alternatively, call Get Marketplace Payouts Aggregate with the same filter plus status not equal to REJECTED to get payoutsTotalAmount directly.

2. Read the matching materialized invoice for that month with Query Materialized Invoices (Materialized Invoices API), filtering on earningsMonth for the same month:

   Copy

3. Compare your marketplace payout total to the invoice's revenueStreamsAggregation.marketplace sub-total for that month. They should match.

4. Check whether the partner has actually been paid by calling Get Last Payment (Materialized Invoices API) and reading the most recent payment's status.