> 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

# QueryGpvPayouts

# Package: earnings

# Namespace: RevShareGpvPayouts

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

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

## Introduction

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


Query Gpv 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: queryGpvPayouts
 Description: Retrieves a list of up to 100 GPV payouts, given the provided paging, filtering, and sorting.   Query Gpv 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/revshare/v1/gpv-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: Number of items to load.  | validation: minimum 0, maximum 100, format int32
        - name: cursor | type: string | description: Pointer to the next or previous page in the list of results.  You can get the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request.  
        - 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"}]`  
           - name: fieldName | type: string | description: Name of the field to sort by.  
           - 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
 Return type: QueryGpvPayoutsResponse
  - name: gpvPayouts | type: array<GpvPayout> | description: List of GpvPayouts.  
     - name: id | type: string | description: GpvPayout GUID.  | read-only: true | validation: format GUID
     - name: revision | type: string | description: Revision number, which increments by 1 each time the GpvPayout is updated. To prevent conflicting changes, the current revision must be passed when updating the GpvPayout.  | 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 day the volume was processed. 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, for example when more volume accrued for the day. Not the day the volume was processed. For that, use `transactionDate`.  | read-only: true | validation: format date-time
     - name: transactionDate | type: string | description: Day the payout is attributed to. Wix maintains a single GpvPayout per `transactionDate`, updating it as volume accrues, so payouts are returned as a flat list of days. Group them client-side if you need monthly totals.  | validation: format date-time
     - name: gpv | type: number | description: Total gross payment volume (GPV) processed across the partner's sites for the transaction date, in USD. Labeled `Client sales` in the Wix Studio dashboard.  | validation: format double
     - name: amount | type: number | description: Amount earned by the partner for this payout, in USD. Calculated as `gpv` multiplied by `paymentRevenueSharePercent`, divided by 100.  | validation: format double
     - name: paymentRevenueSharePercent | type: number | description: Revenue-share rate applied to `gpv` to calculate `amount`. The value is a fractional percent: `0.05` means 0.05% (not 5%), so `amount` = `gpv` * `paymentRevenueSharePercent` / 100. Wix sets the rate automatically based on daily GPV: `0.05` (0.05%) when daily GPV is at or below `2000` USD, and `0.1` (0.1%) when daily GPV is above `2000` USD.  | validation: minimum 0, maximum 100, format double
     - name: sitesGpv | type: array<SiteGpv> | description: The sites whose GPV contributed to this payout, up to 200 sites, each with the volume it contributed. The Wix Studio dashboard shows only the number of sites and the first few site names, so this breakdown is more detailed than the dashboard's.  | validation: maxItems 200
        - name: metaSiteId | type: string | description: GUID of the site.  | validation: format GUID
        - name: gpvInUsd | type: number | description: Gross payment volume processed on the site, in USD.  
        - name: siteName | type: string | description: Name of the site, captured when Wix last calculated this payout. A payout's day is recalculated while volume is still accruing, so a site renamed during that window can show the newer name; once the day is settled the name stops changing. Truncated to 200 UTF-16 code units, so a name using emoji or a non-Latin script can be cut shorter than 200 visible characters. The cut never splits a surrogate pair, but it can split a longer sequence such as an emoji built from several joined characters. Best effort - it may be empty, and it's always empty on payouts created before Wix started capturing it. Use `metaSiteId` as the stable key.  | read-only: true | validation: maxLength 200
     - name: invoiceId | type: string | description: GUID of the invoice this payout was included in. 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.  
  - 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: Offset that was requested.  
        - name: next | type: string | description: Cursor pointing to next page in the list of results.  
        - name: prev | type: string | description: Cursor pointing to previous page in the list of results.  
     - name: hasNext | type: boolean | description: Indicates if there are more results after the current page. If `true`, another page of results can be retrieved. If `false`, this is the last page.  


```

### Examples

### Query Gpv Payouts
Queries GPV payouts for a period, sorted by transaction date

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

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.revshareGpvPayouts.revshareGpvPayouts.queryGpvPayouts(query)
 Description: Retrieves a list of up to 100 GPV payouts, given the provided paging, filtering, and sorting.   Query Gpv 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: GpvPayoutQuery   | 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: Number of items to load.  | validation: minimum 0, maximum 100, format int32
        - name: cursor | type: string | description: Pointer to the next or previous page in the list of results.  You can get the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request.  
        - 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"}]`  
           - name: fieldName | type: string | description: Name of the field to sort by.  
           - 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
 Return type: PROMISE<QueryGpvPayoutsResponse>
  - name: gpvPayouts | type: array<GpvPayout> | description: List of GpvPayouts.  
     - name: _id | type: string | description: GpvPayout GUID.  | read-only: true | validation: format GUID
     - name: revision | type: string | description: Revision number, which increments by 1 each time the GpvPayout is updated. To prevent conflicting changes, the current revision must be passed when updating the GpvPayout.  | 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 day the volume was processed. For that, use `transactionDate`.  | read-only: true 
     - name: _updatedDate | type: Date | description: Date and time the payout record was last updated, for example when more volume accrued for the day. Not the day the volume was processed. For that, use `transactionDate`.  | read-only: true 
     - name: transactionDate | type: Date | description: Day the payout is attributed to. Wix maintains a single GpvPayout per `transactionDate`, updating it as volume accrues, so payouts are returned as a flat list of days. Group them client-side if you need monthly totals.  
     - name: gpv | type: number | description: Total gross payment volume (GPV) processed across the partner's sites for the transaction date, in USD. Labeled `Client sales` in the Wix Studio dashboard.  
     - name: amount | type: number | description: Amount earned by the partner for this payout, in USD. Calculated as `gpv` multiplied by `paymentRevenueSharePercent`, divided by 100.  
     - name: paymentRevenueSharePercent | type: number | description: Revenue-share rate applied to `gpv` to calculate `amount`. The value is a fractional percent: `0.05` means 0.05% (not 5%), so `amount` = `gpv` * `paymentRevenueSharePercent` / 100. Wix sets the rate automatically based on daily GPV: `0.05` (0.05%) when daily GPV is at or below `2000` USD, and `0.1` (0.1%) when daily GPV is above `2000` USD.  | validation: minimum 0, maximum 100
     - name: sitesGpv | type: array<SiteGpv> | description: The sites whose GPV contributed to this payout, up to 200 sites, each with the volume it contributed. The Wix Studio dashboard shows only the number of sites and the first few site names, so this breakdown is more detailed than the dashboard's.  | validation: maxItems 200
        - name: metaSiteId | type: string | description: GUID of the site.  | validation: format GUID
        - name: gpvInUsd | type: number | description: Gross payment volume processed on the site, in USD.  
        - name: siteName | type: string | description: Name of the site, captured when Wix last calculated this payout. A payout's day is recalculated while volume is still accruing, so a site renamed during that window can show the newer name; once the day is settled the name stops changing. Truncated to 200 UTF-16 code units, so a name using emoji or a non-Latin script can be cut shorter than 200 visible characters. The cut never splits a surrogate pair, but it can split a longer sequence such as an emoji built from several joined characters. Best effort - it may be empty, and it's always empty on payouts created before Wix started capturing it. Use `metaSiteId` as the stable key.  | read-only: true | validation: maxLength 200
     - name: invoiceId | type: string | description: GUID of the invoice this payout was included in. 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.  
  - 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: Offset that was requested.  
        - name: next | type: string | description: Cursor pointing to next page in the list of results.  
        - name: prev | type: string | description: Cursor pointing to previous page in the list of results.  
     - name: hasNext | type: boolean | description: Indicates if there are more results after the current page. If `true`, another page of results can be retrieved. If `false`, this is the last page.  


```

### Examples

### Query GPV Payouts
Queries GPV payouts for a period, sorted by transaction date

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

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

async function queryGpvPayouts() {
  const response = await wixPartnersRevshareV1GpvPayout.queryGpvPayouts(query);
}

/* Promise resolves to:
{
  "gpvPayouts": [
    {
      "_id": "8046df3c-7575-4098-a5ab-c91ad8f33c47",
      "revision": "4",
      "_createdDate": "2025-02-01T03:12:08.451Z",
      "_updatedDate": "2025-02-12T06:45:22.119Z",
      "transactionDate": "2025-01-01T00:00:00.000Z",
      "gpv": 8450.75,
      "amount": 8.45,
      "paymentRevenueSharePercent": 0.1,
      "sitesGpv": [
        {
          "metaSiteId": "f1a2b3c4-d5e6-4789-9abc-1234567890ab",
          "siteName": "Northgate Dental",
          "gpvInUsd": 6200.5
        },
        {
          "metaSiteId": "a9b8c7d6-e5f4-4321-8765-0fedcba98765",
          "gpvInUsd": 2250.25
        }
      ],
      "invoiceId": "3c2b1a09-8f7e-4d6c-9b5a-1e2f3a4b5c6d"
    }
  ],
  "pagingMetadata": {
    "count": 1,
    "cursors": {},
    "hasNext": false
  }
}
*/

```

### queryGpvPayouts (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 { revshareGpvPayouts } from '@wix/revshare-gpv-payouts';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

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


async function queryGpvPayouts(query) {
  const response = await myWixClient.revshareGpvPayouts.queryGpvPayouts(query);
};
```

---