> 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

# QueryOrderPaymentRequests

# Package: orders

# Namespace: OrderPaymentRequestsService

# Method link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-payment-requests/query-order-payment-requests.md

## Permission Scopes:
Manage eCommerce - all permissions: SCOPE.DC-ECOM-MEGA.MANAGE-ECOM

## Introduction

Retrieves a list of up to 1,000 order payment requests, given the provided [paging, filtering, and sorting](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md).

Query Order Payment Requests runs with these defaults, which you can override:
- `_createdDate` is sorted in `DESC` order
- `cursorPaging.limit` is `100`

To learn about working with _Query_ endpoints, see
[API Query Language](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md), and
[Sorting and Paging](https://dev.wix.com/docs/rest/articles/getting-started/sorting-and-paging.md).

---

## REST API

### Schema

```
 Method: queryOrderPaymentRequests
 Description: Retrieves a list of up to 1,000 order payment requests, given the provided [paging, filtering, and sorting](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md).  Query Order Payment Requests runs with these defaults, which you can override: - `_createdDate` is sorted in `DESC` order - `cursorPaging.limit` is `100`  To learn about working with _Query_ endpoints, see [API Query Language](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md), and [Sorting and Paging](https://dev.wix.com/docs/rest/articles/getting-started/sorting-and-paging.md).
 URL: https://www.wixapis.com/ecom/v1/order-payment-requests/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, $exists, $in, $hasSome, $startsWith, $gt, $lt, $lte, $gte | sort: none | aggregatable: undefined | searchable: undefined
   - field: orderId | operators: $eq, $ne, $exists, $in, $hasSome, $startsWith, $gt, $lt, $lte, $gte | sort: none | aggregatable: undefined | searchable: undefined
   - field: source.appId | operators: $eq, $ne, $exists, $in, $hasSome, $startsWith, $gt, $lt, $lte, $gte | sort: none | aggregatable: undefined | searchable: undefined
   - field: source.externalId | operators: $eq, $ne, $exists, $in, $hasSome, $startsWith, $gt, $lt, $lte, $gte | sort: none | aggregatable: undefined | searchable: undefined
   - field: paymentGatewayOrderId | operators: $eq, $ne, $exists, $in, $hasSome, $startsWith, $gt, $lt, $lte, $gte | sort: none | aggregatable: undefined | searchable: undefined
   - field: title | operators: $eq, $ne, $exists, $in, $hasSome, $startsWith, $gt, $lt, $lte, $gte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: description | operators: $eq, $ne, $exists, $in, $hasSome, $startsWith, $gt, $lt, $lte, $gte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: status | operators: $eq, $ne, $exists, $in, $hasSome | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: orderNumber | operators: $eq, $ne, $exists, $in, $hasSome, $startsWith, $gt, $lt, $lte, $gte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: expirationDate | operators: $eq, $ne, $exists, $in, $hasSome, $lt, $lte, $gt, $gte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: createdDate | operators: $eq, $ne, $exists, $in, $hasSome, $lt, $lte, $gt, $gte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: updatedDate | operators: $eq, $ne, $exists, $in, $hasSome, $lt, $lte, $gt, $gte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: amount.amount | operators: $eq, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
 Return type: QueryOrderPaymentRequestsResponse
  - name: orderPaymentRequests | type: array<OrderPaymentRequest> | description: List of order payment requests.  | validation: maxItems 1000
     - name: id | type: string | description: Order payment request GUID.  | validation: format GUID
     - name: source | type: Source | description: Details about the source that created the order payment request.  | validation: immutable
        - name: appId | type: string | description: GUID of the app that created the order payment request.  | validation: minLength 1, maxLength 100, format GUID, immutable
        - name: externalId | type: string | description: Reference to a record in the source system. For example, if the payment request was created from a paylink or invoice, use this field to store the paylink GUID or invoice GUID.  | validation: minLength 1, maxLength 100, immutable
     - name: status | type: Status | description: Payment request status. Set by the system. A new order payment request starts as `UNPAID`, unless `expirationDate` is already in the past at creation time, in which case it is created as `EXPIRED`. The system sets the status to `PAID` once payment is collected, `EXPIRED` when the expiration date passes, or `VOIDED` when the request is voided.  
         - enum:
         -     UNPAID: Payment is owed but hasn't been collected yet.
         -     PAID: Payment has been collected.
         -     EXPIRED: The order payment request has passed its `expirationDate` without being paid.
     - name: orderId | type: string | description: Order GUID.  | validation: format GUID, immutable
     - name: orderNumber | type: string | description: Order number.  | validation: maxLength 100
     - name: amount | type: Price | description: Amount to collect. Set when the order payment request is created and can't be changed afterward.  | validation: immutable
        - name: amount | type: string | description: Amount.  | validation: decimalValue {"gte":"0","lte":"1000000000000000"}
        - name: formattedAmount | type: string | description: Amount formatted with currency symbol.  
     - name: currency | type: string | description: Three-letter currency code in [ISO-4217 alphabetic format](http://en.wikipedia.org/wiki/ISO_4217). Always matches the order's currency.  | validation: format CURRENCY
     - name: paymentGatewayOrderId | type: string | description: Payment gateway order GUID associated with this payment request.  | validation: minLength 1, maxLength 100
     - name: title | type: string | description: Title displayed to the customer on the payment page.  | validation: minLength 1, maxLength 200
     - name: description | type: string | description: Description displayed to the customer on the payment page.  | validation: maxLength 300
     - name: expirationDate | type: string | description: Date and time the order payment request expires. If not provided, the order payment request doesn't expire.  | validation: format date-time, immutable
     - name: extendedFields | type: ExtendedFields | description: Custom field data for this order payment request.  [Extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) must be configured in the app dashboard before they can be accessed with API calls.  
        - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured.  You can only access fields for which you have the appropriate permissions.  Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md).  | validation: format map
     - name: createdDate | type: string | description: Date and time the order payment request was created.  | validation: format date-time
     - name: updatedDate | type: string | description: Date and time the order payment request was last updated.  | validation: format date-time
     - name: image | type: Image | description: Image to display to the customer on the payment page.  
        - name: id | type: string | description: WixMedia image GUID.  | validation: maxLength 200
        - name: height | type: integer | description: Original image height.  
        - name: width | type: integer | description: Original image width.  
        - name: altText | type: string | description: Image alt text.  | validation: maxLength 200
        - name: filename | type: string | description: Image filename.  | validation: maxLength 200
     - name: blockedPaymentMethods | type: array<PaymentMethod> | description: List of payment methods that can't be used for this order payment request.  | validation: maxItems 1
         - enum:
         -     MANUAL: Manual payment.
  - 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 Order Payment Requests
Retrieves a list of order payment requests for a specific order, filtered by status.

```curl
curl -X POST \
  'https://www.wixapis.com/ecom/v1/order-payment-requests/query' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: <AUTH>' \
  -d '{
    "query": {
      "filter": {
        "orderId": { "$eq": "a931e280-254a-49a7-9641-22ef64c444ae" },
        "status": { "$eq": "UNPAID" }
      },
      "sort": [{ "fieldName": "createdDate", "order": "DESC" }],
      "cursorPaging": { "limit": 10 }
    }
  }'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.ecom.orderPaymentRequests.queryOrderPaymentRequests(query)
 Description: Retrieves a list of up to 1,000 order payment requests, given the provided [paging, filtering, and sorting](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md).  Query Order Payment Requests runs with these defaults, which you can override: - `_createdDate` is sorted in `DESC` order - `cursorPaging.limit` is `100`  To learn about working with _Query_ endpoints, see [API Query Language](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md), and [Sorting and Paging](https://dev.wix.com/docs/rest/articles/getting-started/sorting-and-paging.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: OrderPaymentRequestQuery   | 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, $exists, $in, $hasSome, $startsWith, $gt, $lt, $lte, $gte | sort: none | aggregatable: undefined | searchable: undefined
   - field: orderId | operators: $eq, $ne, $exists, $in, $hasSome, $startsWith, $gt, $lt, $lte, $gte | sort: none | aggregatable: undefined | searchable: undefined
   - field: source.appId | operators: $eq, $ne, $exists, $in, $hasSome, $startsWith, $gt, $lt, $lte, $gte | sort: none | aggregatable: undefined | searchable: undefined
   - field: source.externalId | operators: $eq, $ne, $exists, $in, $hasSome, $startsWith, $gt, $lt, $lte, $gte | sort: none | aggregatable: undefined | searchable: undefined
   - field: paymentGatewayOrderId | operators: $eq, $ne, $exists, $in, $hasSome, $startsWith, $gt, $lt, $lte, $gte | sort: none | aggregatable: undefined | searchable: undefined
   - field: title | operators: $eq, $ne, $exists, $in, $hasSome, $startsWith, $gt, $lt, $lte, $gte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: description | operators: $eq, $ne, $exists, $in, $hasSome, $startsWith, $gt, $lt, $lte, $gte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: status | operators: $eq, $ne, $exists, $in, $hasSome | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: orderNumber | operators: $eq, $ne, $exists, $in, $hasSome, $startsWith, $gt, $lt, $lte, $gte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: expirationDate | operators: $eq, $ne, $exists, $in, $hasSome, $lt, $lte, $gt, $gte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: _createdDate | operators: $eq, $ne, $exists, $in, $hasSome, $lt, $lte, $gt, $gte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: _updatedDate | operators: $eq, $ne, $exists, $in, $hasSome, $lt, $lte, $gt, $gte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: amount.amount | operators: $eq, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
 Return type: PROMISE<QueryOrderPaymentRequestsResponse>
  - name: orderPaymentRequests | type: array<OrderPaymentRequest> | description: List of order payment requests.  | validation: maxItems 1000
     - name: _id | type: string | description: Order payment request GUID.  | validation: format GUID
     - name: source | type: Source | description: Details about the source that created the order payment request.  | validation: immutable
        - name: appId | type: string | description: GUID of the app that created the order payment request.  | validation: minLength 1, maxLength 100, format GUID, immutable
        - name: externalId | type: string | description: Reference to a record in the source system. For example, if the payment request was created from a paylink or invoice, use this field to store the paylink GUID or invoice GUID.  | validation: minLength 1, maxLength 100, immutable
     - name: status | type: Status | description: Payment request status. Set by the system. A new order payment request starts as `UNPAID`, unless `expirationDate` is already in the past at creation time, in which case it is created as `EXPIRED`. The system sets the status to `PAID` once payment is collected, `EXPIRED` when the expiration date passes, or `VOIDED` when the request is voided.  
         - enum:
         -     UNPAID: Payment is owed but hasn't been collected yet.
         -     PAID: Payment has been collected.
         -     EXPIRED: The order payment request has passed its `expirationDate` without being paid.
     - name: orderId | type: string | description: Order GUID.  | validation: format GUID, immutable
     - name: orderNumber | type: string | description: Order number.  | validation: maxLength 100
     - name: amount | type: Price | description: Amount to collect. Set when the order payment request is created and can't be changed afterward.  | validation: immutable
        - name: amount | type: string | description: Amount.  | validation: decimalValue {"gte":"0","lte":"1000000000000000"}
        - name: formattedAmount | type: string | description: Amount formatted with currency symbol.  
     - name: currency | type: string | description: Three-letter currency code in [ISO-4217 alphabetic format](http://en.wikipedia.org/wiki/ISO_4217). Always matches the order's currency.  | validation: format CURRENCY
     - name: paymentGatewayOrderId | type: string | description: Payment gateway order GUID associated with this payment request.  | validation: minLength 1, maxLength 100
     - name: title | type: string | description: Title displayed to the customer on the payment page.  | validation: minLength 1, maxLength 200
     - name: description | type: string | description: Description displayed to the customer on the payment page.  | validation: maxLength 300
     - name: expirationDate | type: Date | description: Date and time the order payment request expires. If not provided, the order payment request doesn't expire.  | validation: immutable
     - name: extendedFields | type: ExtendedFields | description: Custom field data for this order payment request.  [Extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) must be configured in the app dashboard before they can be accessed with API calls.  
        - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured.  You can only access fields for which you have the appropriate permissions.  Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md).  | validation: format map
     - name: _createdDate | type: Date | description: Date and time the order payment request was created.  
     - name: _updatedDate | type: Date | description: Date and time the order payment request was last updated.  
     - name: image | type: string | description: Image to display to the customer on the payment page.  
     - name: blockedPaymentMethods | type: array<PaymentMethod> | description: List of payment methods that can't be used for this order payment request.  | validation: maxItems 1
         - enum:
         -     MANUAL: Manual payment.
  - 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 order payment requests
Retrieves unpaid order payment requests for a specific order, sorted by creation date in descending order.

```javascript

import { orderPaymentRequests } from '@wix/ecom';

export async function myQueryOrderPaymentRequestsFunction() {
  try {
    const response = await orderPaymentRequests
      .queryOrderPaymentRequests()
      .eq('orderId', 'a931e280-254a-49a7-9641-22ef64c444ae')
      .eq('status', 'UNPAID')
      .descending('_createdDate')
      .limit(10)
      .find();
    console.log('Success! Order payment requests:', response.items);
    return response;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}

/* Promise resolves to:
 * {
 *   "items": [
 *     {
 *       "_id": "3c8f1a2e-7b4d-4f9e-8c61-5d2e9a0b1c3f",
 *       "status": "UNPAID",
 *       "orderId": "a931e280-254a-49a7-9641-22ef64c444ae",
 *       "orderNumber": "10052",
 *       "amount": {
 *         "amount": "15.50",
 *         "formattedAmount": "$15.50"
 *       },
 *       "currency": "USD",
 *       "paymentGatewayOrderId": "e7a4b2c9-1f3d-4a8e-9b6c-2d5f8a1e4c7b",
 *       "title": "Balance Due for Order #10052",
 *       "description": "Remaining balance for your recent purchase",
 *       "expirationDate": "2026-07-15T23:59:59.000Z",
 *       "_createdDate": "2026-06-01T14:22:18.456Z",
 *       "_updatedDate": "2026-06-01T14:22:18.456Z"
 *     }
 *   ],
 *   "cursors": {},
 *   "hasNext": () => boolean,
 *   "hasPrev": () => boolean,
 *   "length": 1,
 *   "pageSize": 10
 * }
 */

```

### queryOrderPaymentRequests (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 { orderPaymentRequests } from '@wix/ecom';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

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


async function queryOrderPaymentRequests(query) {
  const response = await myWixClient.orderPaymentRequests.queryOrderPaymentRequests(query);
};
```

---