> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# QueryMarketplacePayouts

# Package: earnings

# Namespace: MarketplacePayouts

# Method link: https://dev.wix.com/docs/api-reference/account-level/studio-workspace/earnings/marketplace-payout-v1/query-marketplace-payouts.md

## Permission Scopes:
SCOPE.PARTNERS.REVSHARE: SCOPE.PARTNERS.REVSHARE

## Introduction

Retrieves a list of up to 100 marketplace payouts, given the provided paging, filtering, and sorting.


Query Marketplace Payouts runs with these defaults, which you can override:

- `createdDate` is sorted in `DESC` order
- `paging.limit` is `100`
- `paging.offset` is `0`

To learn about working with Query methods, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md), and [Field Projection](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-field-projection.md).

---

## REST API

### Schema

```
 Method: queryMarketplacePayouts
 Description: Retrieves a list of up to 100 marketplace payouts, given the provided paging, filtering, and sorting.   Query Marketplace Payouts runs with these defaults, which you can override:  - `createdDate` is sorted in `DESC` order - `paging.limit` is `100` - `paging.offset` is `0`  To learn about working with Query methods, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md), and [Field Projection](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-field-projection.md).
 URL: https://www.wixapis.com/partners/marketplace/v1/marketplace-payouts/query
 Method: POST
 Method parameters:
   param name: query | type: CursorQuery    
     - name: cursorPaging | type: CursorPaging | description: Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`.  
        - name: limit | type: integer | description: Maximum number of items to return in the results.  | validation: minimum 0, maximum 100, format int32
        - name: cursor | type: string | description: Pointer to the next or previous page in the list of results.  Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request.  | validation: maxLength 16000
        - name: filter | type: object | description: Filter object in the following format: `"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }` Example of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains`  
        - name: sort | type: array<Sorting> | description: Sort object in the following format: `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]`  | validation: maxItems 5
           - name: fieldName | type: string | description: Name of the field to sort by.  | validation: maxLength 512
           - name: order | type: SortOrder | description: Sort order.  
                 - enum: ASC, DESC
 Query fields:
   - field: id | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte, $startsWith | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: createdDate | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: transactionDate | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: amount | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: transactionAmount | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: paymentSharePercent | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: listing | operators: $exists | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: listing.id | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte, $startsWith | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: listing.type | operators: $eq, $ne, $in, $exists | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: invoiceId | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte, $startsWith | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
 Return type: QueryMarketplacePayoutsResponse
  - name: marketplacePayouts | type: array<MarketplacePayout> | description: Retrieved list of marketplace payouts.  
     - name: id | type: string | description: MarketplacePayout GUID.  | read-only: true | validation: format GUID
     - name: revision | type: string | description: Revision number, which increments by 1 each time the MarketplacePayout is updated. To prevent conflicting changes, the current revision must be passed when updating the MarketplacePayout.  | read-only: true | validation: format int64
     - name: createdDate | type: string | description: Date and time the payout record was created in Wix's systems. This is record bookkeeping, not the date of the marketplace transaction. For that, use `transactionDate`.  | read-only: true | validation: format date-time
     - name: updatedDate | type: string | description: Date and time the payout record was last updated. Not the date of the marketplace transaction. For that, use `transactionDate`.  | read-only: true | validation: format date-time
     - name: listing | type: Listing | description: The marketplace listing the transaction was made on, for example the template that was sold. The Wix Studio dashboard displays the listing's name instead of its GUID and type.  
        - name: id | type: string | description: GUID of the listing.  | validation: format GUID
        - name: type | type: Type | description: Type of the listing.  
             - enum:
             -     UNKNOWN: Unknown listing type.
             -     TEMPLATE: A template listing.
     - name: transactionAmount | type: number | description: Total price of the marketplace transaction, converted to and stored in USD.  | validation: format double
     - name: paymentSharePercent | type: number | description: Fractional percent of `transactionAmount` the partner earns as revenue share, used to calculate `amount`. For example, a value of `0.05` means 0.05%.  | validation: format double
     - name: amount | type: number | description: Revenue share the partner earned on this transaction, in USD. Calculated as `transactionAmount` multiplied by `paymentSharePercent`, divided by 100.  | validation: format double
     - name: transactionDate | type: string | description: Date and time the marketplace transaction took place, which is when the payout was earned.  | validation: format date-time
     - name: invoiceId | type: string | description: GUID of the invoice this payout was included in, once invoiced. Empty until the payout is invoiced.  This is the reference code of the partner's invoice. To resolve it, query the Materialized Invoices API for the materialized invoice whose `invoicesRefCodes` contains this value, and read that invoice's `status` to see whether it was paid.  | validation: maxLength 50
     - name: status | type: Status | description: Status of the marketplace payout. - `APPROVED`: Eligible to be invoiced. Shown as `Paid` in the Wix Studio dashboard, or as `Reversed` when `negative` is `true`. - `REJECTED`: Won't be paid. Shown as `Cancelled` in the Wix Studio dashboard, and excluded from the dashboard's earnings total.  
         - enum:
         -     APPROVED: Eligible to be invoiced. Shown as `Paid` in the Wix Studio dashboard, or as `Reversed` when `negative` is `true`.
         -     REJECTED: Won't be paid. Shown as `Cancelled` in the Wix Studio dashboard, and excluded from its earnings total.
     - name: negative | type: boolean | description: Whether this payout is a reversal or cancellation of an earlier payout. When `true`, the payout offsets a previous earning, so its `amount` reduces the partner's total. One positive and one negative payout are allowed per transaction. Reversals are returned by queries like any other payout, and count toward totals, so don't filter them out when summing.  
  - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata.  
     - name: count | type: integer | description: Number of items returned in the response.  | validation: format int32
     - name: cursors | type: Cursors | description: Cursor strings that point to the next page, previous page, or both.  
        - name: next | type: string | description: Cursor string pointing to the next page in the list of results.  | validation: maxLength 16000
        - name: prev | type: string | description: Cursor pointing to the previous page in the list of results.  | validation: maxLength 16000
     - name: hasNext | type: boolean | description: Whether there are more pages to retrieve following the current page.  + `true`: Another page of results can be retrieved. + `false`: This is the last page.  


```

### Examples

### Query Marketplace Payouts
Queries a partner's marketplace payouts for a date range, sorted by transaction date

```curl
curl -X POST \
  'https://www.wixapis.com/v1/marketplace-payouts/query' \
  -H 'Authorization: <AUTH>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "transactionDate": {
          "$gte": "2026-05-01T00:00:00.000Z",
          "$lt": "2026-06-01T00:00:00.000Z"
        }
      },
      "sort": [
        { "fieldName": "transactionDate", "order": "DESC" }
      ],
      "cursorPaging": { "limit": 100 }
    }
  }'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.marketplacePayouts.marketplacePayouts.queryMarketplacePayouts(query)
 Description: Retrieves a list of up to 100 marketplace payouts, given the provided paging, filtering, and sorting.   Query Marketplace Payouts runs with these defaults, which you can override:  - `createdDate` is sorted in `DESC` order - `paging.limit` is `100` - `paging.offset` is `0`  To learn about working with Query methods, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md), and [Field Projection](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-field-projection.md).
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  query
 Method parameters: 
   param name: query | type: MarketplacePayoutQuery   | required: true 
     - name: cursorPaging | type: CursorPaging | description: Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`.  
        - name: limit | type: integer | description: Maximum number of items to return in the results.  | validation: minimum 0, maximum 100, format int32
        - name: cursor | type: string | description: Pointer to the next or previous page in the list of results.  Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request.  | validation: maxLength 16000
        - name: filter | type: object | description: Filter object in the following format: `"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }` Example of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains`  
        - name: sort | type: array<Sorting> | description: Sort object in the following format: `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]`  | validation: maxItems 5
           - name: fieldName | type: string | description: Name of the field to sort by.  | validation: maxLength 512
           - name: order | type: SortOrder | description: Sort order.  
                 - enum: ASC, DESC
 Query fields:
   - field: _id | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte, $startsWith | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: _createdDate | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: transactionDate | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: amount | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: transactionAmount | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: paymentSharePercent | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: listing | operators: $exists | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: listing._id | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte, $startsWith | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: listing.type | operators: $eq, $ne, $in, $exists | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: invoiceId | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte, $startsWith | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
 Return type: PROMISE<QueryMarketplacePayoutsResponse>
  - name: marketplacePayouts | type: array<MarketplacePayout> | description: Retrieved list of marketplace payouts.  
     - name: _id | type: string | description: MarketplacePayout GUID.  | read-only: true | validation: format GUID
     - name: revision | type: string | description: Revision number, which increments by 1 each time the MarketplacePayout is updated. To prevent conflicting changes, the current revision must be passed when updating the MarketplacePayout.  | read-only: true | validation: format int64
     - name: _createdDate | type: Date | description: Date and time the payout record was created in Wix's systems. This is record bookkeeping, not the date of the marketplace transaction. For that, use `transactionDate`.  | read-only: true 
     - name: _updatedDate | type: Date | description: Date and time the payout record was last updated. Not the date of the marketplace transaction. For that, use `transactionDate`.  | read-only: true 
     - name: listing | type: Listing | description: The marketplace listing the transaction was made on, for example the template that was sold. The Wix Studio dashboard displays the listing's name instead of its GUID and type.  
        - name: _id | type: string | description: GUID of the listing.  | validation: format GUID
        - name: type | type: Type | description: Type of the listing.  
             - enum:
             -     UNKNOWN: Unknown listing type.
             -     TEMPLATE: A template listing.
     - name: transactionAmount | type: number | description: Total price of the marketplace transaction, converted to and stored in USD.  
     - name: paymentSharePercent | type: number | description: Fractional percent of `transactionAmount` the partner earns as revenue share, used to calculate `amount`. For example, a value of `0.05` means 0.05%.  
     - name: amount | type: number | description: Revenue share the partner earned on this transaction, in USD. Calculated as `transactionAmount` multiplied by `paymentSharePercent`, divided by 100.  
     - name: transactionDate | type: Date | description: Date and time the marketplace transaction took place, which is when the payout was earned.  
     - name: invoiceId | type: string | description: GUID of the invoice this payout was included in, once invoiced. Empty until the payout is invoiced.  This is the reference code of the partner's invoice. To resolve it, query the Materialized Invoices API for the materialized invoice whose `invoicesRefCodes` contains this value, and read that invoice's `status` to see whether it was paid.  | validation: maxLength 50
     - name: status | type: Status | description: Status of the marketplace payout. - `APPROVED`: Eligible to be invoiced. Shown as `Paid` in the Wix Studio dashboard, or as `Reversed` when `negative` is `true`. - `REJECTED`: Won't be paid. Shown as `Cancelled` in the Wix Studio dashboard, and excluded from the dashboard's earnings total.  
         - enum:
         -     APPROVED: Eligible to be invoiced. Shown as `Paid` in the Wix Studio dashboard, or as `Reversed` when `negative` is `true`.
         -     REJECTED: Won't be paid. Shown as `Cancelled` in the Wix Studio dashboard, and excluded from its earnings total.
     - name: negative | type: boolean | description: Whether this payout is a reversal or cancellation of an earlier payout. When `true`, the payout offsets a previous earning, so its `amount` reduces the partner's total. One positive and one negative payout are allowed per transaction. Reversals are returned by queries like any other payout, and count toward totals, so don't filter them out when summing.  
  - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata.  
     - name: count | type: integer | description: Number of items returned in the response.  | validation: format int32
     - name: cursors | type: Cursors | description: Cursor strings that point to the next page, previous page, or both.  
        - name: next | type: string | description: Cursor string pointing to the next page in the list of results.  | validation: maxLength 16000
        - name: prev | type: string | description: Cursor pointing to the previous page in the list of results.  | validation: maxLength 16000
     - name: hasNext | type: boolean | description: Whether there are more pages to retrieve following the current page.  + `true`: Another page of results can be retrieved. + `false`: This is the last page.  


```

### Examples

### Query Marketplace Payouts
Queries a partner's marketplace payouts for a date range, sorted by transaction date

```javascript
import { wixPartnersMarketplaceV1MarketplacePayout } from "@wix/dev";

const query = {
  filter: {
    transactionDate: {
      $gte: "2026-05-01T00:00:00.000Z",
      $lt: "2026-06-01T00:00:00.000Z",
    },
  },
  sort: [{ fieldName: "transactionDate", order: "DESC" }],
  cursorPaging: { limit: 100 },
};

async function queryMarketplacePayouts() {
  const response =
    await wixPartnersMarketplaceV1MarketplacePayout.queryMarketplacePayouts(
      query
    );
}

/* Promise resolves to:
{
  "marketplacePayouts": [
    {
      "_id": "3f1c8e2a-9b47-4d1e-8a6f-2c5b7e9d0a14",
      "revision": "1",
      "_createdDate": "2026-05-14T08:21:33.512Z",
      "_updatedDate": "2026-05-14T08:21:33.512Z",
      "listing": {
        "id": "a1c2e3f4-5b6d-4789-9012-3456789abcde",
        "type": "TEMPLATE"
      },
      "transactionAmount": 79,
      "paymentSharePercent": 100,
      "amount": 79,
      "transactionDate": "2026-05-14T08:21:30.000Z",
      "invoiceId": "",
      "status": "APPROVED",
      "negative": false
    },
    {
      "_id": "c9e2a1b0-7d34-4e62-8f51-0a9b3c6d2e75",
      "revision": "1",
      "_createdDate": "2026-05-09T15:02:11.004Z",
      "_updatedDate": "2026-05-09T15:02:11.004Z",
      "listing": {
        "id": "f4e3d2c1-6b5a-4987-8210-fedcba987654",
        "type": "TEMPLATE"
      },
      "transactionAmount": 120,
      "paymentSharePercent": 100,
      "amount": 120,
      "transactionDate": "2026-05-09T15:02:08.000Z",
      "invoiceId": "INV-2026-05-0042",
      "status": "APPROVED",
      "negative": false
    }
  ],
  "pagingMetadata": {
    "cursors": {},
    "hasNext": false
  }
}
*/

```

### queryMarketplacePayouts (self-hosted)
Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md).

```javascript
import { createClient } from '@wix/sdk';
import { marketplacePayouts } from '@wix/marketplace-payouts';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { marketplacePayouts },
  // Include the auth strategy and host as relevant
});


async function queryMarketplacePayouts(query) {
  const response = await myWixClient.marketplacePayouts.queryMarketplacePayouts(query);
};
```

---