> 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 # QueryMaterializedInvoices # Package: earnings # Namespace: MaterializedInvoices # Method link: https://dev.wix.com/docs/api-reference/account-level/studio-workspace/earnings/materialized-invoice-v1/query-materialized-invoices.md ## Permission Scopes: SCOPE.PARTNERS.REVSHARE: SCOPE.PARTNERS.REVSHARE ## Introduction Retrieves a list of up to 100 materialized invoices, given the provided paging, filtering, and sorting. Query Materialized Invoices runs with these defaults, which you can override: - `earningsMonth` 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: queryMaterializedInvoices Description: Retrieves a list of up to 100 materialized invoices, given the provided paging, filtering, and sorting. Query Materialized Invoices runs with these defaults, which you can override: - `earningsMonth` 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/materialized-invoices/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 | 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: amount | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined - field: status | operators: $eq, $ne, $in, $exists | sort: ASC, DESC | aggregatable: undefined | searchable: undefined - field: earningsMonth | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined - field: invoicesRefCodes | operators: $hasSome, $hasAll, $exists, $isEmpty | sort: ASC, DESC | aggregatable: undefined | searchable: undefined Return type: QueryMaterializedInvoicesResponse - name: materializedInvoices | type: array | description: Retrieved materialized invoices. - name: id | type: string | description: Materialized invoice GUID. | read-only: true | validation: format GUID - name: earningsMonth | type: string | description: Earnings month the invoice covers. This is a month bucket, not an exact instant. It's normalized to the start of the day on the first day of the month. The underlying invoices are grouped into one materialized invoice per earnings month per payment status. | validation: format date-time - name: invoicesRefCodes | type: array | description: Reference codes of the underlying invoices included in this aggregation. A reference code is the identifier assigned by the payment handler (Tipalti) to each invoice. It's the same value that a premium, GPV, or marketplace payout carries in its `invoiceId`, so you can filter on this field to find the invoice a payout was included in. | validation: maxItems 9999, minLength 1, maxLength 16 - name: amount | type: number | description: Total amount across the grouped invoices, in USD. Equals the sum of the `revenueStreamsAggregation` sub-totals. - name: status | type: Status | description: Payment status of the grouped invoices for the earnings month. - enum: - UNPAID: The invoice is scheduled for payment but not yet paid. - PAID: The invoice has been paid. - BELOW_THRESHOLD: The total unpaid amount across all of the partner's unpaid invoices is below the payout threshold, so payment isn't yet scheduled. Payment is scheduled once the threshold is reached. - name: revenueStreamsAggregation | type: RevenueStreamsAggregation | description: Invoice total broken down into its premium, GPV, marketplace, and app market revenue-stream sub-totals. - name: premium | type: number | description: Total premium earnings from premium subscriptions the partner sold, in USD. | validation: format double - name: gpv | type: number | description: Total GPV earnings, in USD. GPV (gross payment volume) is the payment volume processed across the sites the partner manages. | validation: format double - name: marketplace | type: number | description: Total marketplace earnings from marketplace transactions, such as template sales, in USD. | validation: format double - name: appMarket | type: number | description: Total app market earnings, in USD. This is a fourth revenue stream alongside premium, GPV, and marketplace, so include it when you add the sub-totals up to the invoice's `amount`. | validation: format double - 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 Materialized Invoices Queries a partner's materialized invoices for a month, sorted by earnings month ```curl curl -X POST \ 'https://www.wixapis.com/partners/revshare/v1/materialized-invoices/query' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "query": { "filter": { "earningsMonth": "2026-05-01T00:00:00.000Z", "status": "PAID" }, "sort": [ { "fieldName": "earningsMonth", "order": "ASC" } ], "cursorPaging": { "limit": 100 } } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.revshareMaterializedInvoices.revshareMaterializedInvoices.queryMaterializedInvoices(query) Description: Retrieves a list of up to 100 materialized invoices, given the provided paging, filtering, and sorting. Query Materialized Invoices runs with these defaults, which you can override: - `earningsMonth` 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: MaterializedInvoiceQuery | 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 | 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: amount | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined - field: status | operators: $eq, $ne, $in, $exists | sort: ASC, DESC | aggregatable: undefined | searchable: undefined - field: earningsMonth | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined - field: invoicesRefCodes | operators: $hasSome, $hasAll, $exists, $isEmpty | sort: ASC, DESC | aggregatable: undefined | searchable: undefined Return type: PROMISE - name: materializedInvoices | type: array | description: Retrieved materialized invoices. - name: _id | type: string | description: Materialized invoice GUID. | read-only: true | validation: format GUID - name: earningsMonth | type: Date | description: Earnings month the invoice covers. This is a month bucket, not an exact instant. It's normalized to the start of the day on the first day of the month. The underlying invoices are grouped into one materialized invoice per earnings month per payment status. - name: invoicesRefCodes | type: array | description: Reference codes of the underlying invoices included in this aggregation. A reference code is the identifier assigned by the payment handler (Tipalti) to each invoice. It's the same value that a premium, GPV, or marketplace payout carries in its `invoiceId`, so you can filter on this field to find the invoice a payout was included in. | validation: maxItems 9999, minLength 1, maxLength 16 - name: amount | type: number | description: Total amount across the grouped invoices, in USD. Equals the sum of the `revenueStreamsAggregation` sub-totals. - name: status | type: Status | description: Payment status of the grouped invoices for the earnings month. - enum: - UNPAID: The invoice is scheduled for payment but not yet paid. - PAID: The invoice has been paid. - BELOW_THRESHOLD: The total unpaid amount across all of the partner's unpaid invoices is below the payout threshold, so payment isn't yet scheduled. Payment is scheduled once the threshold is reached. - name: revenueStreamsAggregation | type: RevenueStreamsAggregation | description: Invoice total broken down into its premium, GPV, marketplace, and app market revenue-stream sub-totals. - name: premium | type: number | description: Total premium earnings from premium subscriptions the partner sold, in USD. - name: gpv | type: number | description: Total GPV earnings, in USD. GPV (gross payment volume) is the payment volume processed across the sites the partner manages. - name: marketplace | type: number | description: Total marketplace earnings from marketplace transactions, such as template sales, in USD. - name: appMarket | type: number | description: Total app market earnings, in USD. This is a fourth revenue stream alongside premium, GPV, and marketplace, so include it when you add the sub-totals up to the invoice's `amount`. - 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 materialized invoices for a month Queries a partner's materialized invoices for a month, sorted by earnings month ```javascript import { revshareMaterializedInvoices } from "@wix/revshare-materialized-invoices"; const query = { filter: { earningsMonth: "2026-05-01T00:00:00.000Z", status: "PAID", }, sort: [{ fieldName: "earningsMonth", order: "ASC" }], cursorPaging: { limit: 100 }, }; async function queryMaterializedInvoices() { const response = await revshareMaterializedInvoices.queryMaterializedInvoices( query, ); } /* Promise resolves to: * { * "materializedInvoices": [ * { * "_id": "3f9a5c21-8b4e-4f0d-9c7a-2e6b1d4f8a90", * "earningsMonth": "2026-05-01T00:00:00.000Z", * "invoicesRefCodes": ["INV-2026-05-0007", "INV-2026-05-0012"], * "amount": 1842.50, * "status": "PAID", * "revenueStreamsAggregation": { * "premium": 1200.00, * "gpv": 442.50, * "marketplace": 200.00 * } * } * ], * "pagingMetadata": { * "count": 1, * "cursors": {}, * "hasNext": false * } * } */ ``` ### queryMaterializedInvoices (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 { revshareMaterializedInvoices } from '@wix/revshare-materialized-invoices'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { revshareMaterializedInvoices }, // Include the auth strategy and host as relevant }); async function queryMaterializedInvoices(query) { const response = await myWixClient.revshareMaterializedInvoices.queryMaterializedInvoices(query); }; ``` ---