> 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

# QueryPromotions

# Package: catalogV3

# Namespace: PromotionsService

# Method link: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/promotions-v3/query-promotions.md

## Permission Scopes:
Read v3 catalog: SCOPE.STORES.CATALOG_READ

## Introduction

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


Query Promotions runs with these defaults, which you can override:

- `createdDate` is sorted in `DESC` order
- `cursorPaging.limit` is `100`

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: queryPromotions
 Description: Retrieves a list of up to 100 promotions, given the provided paging, filtering, and sorting.   Query Promotions runs with these defaults, which you can override:  - `createdDate` is sorted in `DESC` order - `cursorPaging.limit` is `100`  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/stores/v3/promotions/query
 Method: POST
 Method parameters:
   param name: query | type: CursorQuery    
     - name: cursorPaging | type: CursorPaging | description: Cursor paging options.  Learn more about [cursor paging](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md#cursor-paging).  
        - 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.  Learn more about the [filter section](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md#the-filter-section).  
        - name: sort | type: array<Sorting> | description: Sort object.  Learn more about the [sort section](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md#the-sort-section).  | 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: 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: enabled | operators: $eq, $ne, $exists, $in, $hasSome | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: tags.publicTags.tagIds | operators: $eq, $ne, $exists, $in, $hasSome, $hasAll | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: tags.privateTags.tagIds | operators: $eq, $ne, $exists, $in, $hasSome, $hasAll | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
 Return type: QueryPromotionsResponse
  - name: promotions | type: array<Promotion> | description: List of promotions.  
     - name: id | type: string | description: Promotion GUID.  | validation: format GUID
     - name: revision | type: string | description: Revision number, which increments by 1 each time the promotion is updated. To prevent conflicting changes, the current revision must be passed when updating the promotion.  | validation: format int64
     - name: createdDate | type: string | description: Date and time the promotion was created.  | validation: format date-time
     - name: updatedDate | type: string | description: Date and time the promotion was last updated.  | validation: format date-time
     - name: name | type: string | description: Promotion name.  | validation: minLength 1, maxLength 50
     - name: media | type: PromotionMedia | description: Promotion media.  
        - ONE-OF: 
           - name: id | type: string | description: Set media by GUID of an existing file in Wix Media Manager.  | validation: minLength 1, maxLength 200
           - name: url | type: string | description: Set media using an external media URL.  When provided, Wix Media Manager imports the media asynchronously. During import: - `image` is empty. - The promotion is saved as disabled regardless of the requested `enabled` value.  Once the import completes successfully, the promotion's `image` is populated and `enabled` is set to the originally requested value. If the import fails, the promotion's entire `media` object is cleared and the promotion stays disabled. To retry, set new media.  | validation: format WEB_URL
        - name: altText | type: string | description: Image alt text.  | validation: minLength 1, maxLength 1000
        - name: displayName | type: string | description: Media display name.  Overrides the default media name. Can be passed only when the media is set by a URL in this item's `url` field.  | validation: maxLength 80
        - name: mediaType | type: MediaType | description: Media type.  
             - enum:
             -     IMAGE: Image media type.
        - name: uploadId | type: string | description: GUID of the asynchronous media import that Wix Media Manager runs when media is set with a `url`.  | validation: format GUID
     - name: destinationUrl | type: string | description: URL the promotion redirects to when a customer clicks the banner.  | validation: format WEB_URL
     - name: categories | type: array<CategoryAssignment> | description: Categories the promotion is directly assigned to. A promotion may also appear in subcategories when `appliedToSubcategories` is `true` for a directly assigned category.  | validation: maxItems 1000
        - name: id | type: string | description: Category GUID.  | validation: format GUID
        - name: position | type: integer | description: Position of the promotion within the category, starting from 1.  Must be provided for each category assignment — omitting it fails validation, because positions start from 1.  | validation: minimum 1
        - name: appliedToSubcategories | type: boolean | description: Whether the promotion also appears in this category's subcategories. When inherited by a subcategory, the promotion keeps the same position.  Default: `false`  
     - name: enabled | type: boolean | description: Whether the promotion is enabled.  When creating or updating with `media.url`, this value takes effect only after the media import completes successfully. See `media.url` for details.  Default: `false`  
     - name: extendedFields | type: ExtendedFields | description: Custom field data for the promotion object.  [Extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.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: tags | type: Tags | description: Tags for organizing and filtering promotions.  
        - name: privateTags | type: TagList | description: Tags that require an additional permission in order to access them, normally not given to site members or visitors.  
           - name: tagIds | type: array<string> | description: List of tag GUIDs.  | validation: maxItems 100, maxLength 5
        - name: publicTags | type: TagList | description: Tags that are exposed to anyone who has access to the labeled entity itself, including site members and visitors.  
  - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata.  
     - name: count | type: integer | description: Number of items returned in current page.  | 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 Promotions
Retrieves enabled promotions sorted by creation date in descending order.

```curl
curl -X POST \
  'https://www.wixapis.com/stores/v3/promotions/query' \
  -H 'Authorization: <AUTH>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "enabled": true
      },
      "sort": [
        {
          "fieldName": "createdDate",
          "order": "DESC"
        }
      ],
      "cursorPaging": {
        "limit": 10
      }
    }
  }'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.stores.promotionsV3.queryPromotions(query)
 Description: Retrieves a list of up to 100 promotions, given the provided paging, filtering, and sorting.   Query Promotions runs with these defaults, which you can override:  - `createdDate` is sorted in `DESC` order - `cursorPaging.limit` is `100`  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: PromotionQuery   | required: true 
     - name: cursorPaging | type: CursorPaging | description: Cursor paging options.  Learn more about [cursor paging](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md#cursor-paging).  
        - 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.  Learn more about the [filter section](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md#the-filter-section).  
        - name: sort | type: array<Sorting> | description: Sort object.  Learn more about the [sort section](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md#the-sort-section).  | 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: 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: enabled | operators: $eq, $ne, $exists, $in, $hasSome | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: tags.publicTags.tagIds | operators: $eq, $ne, $exists, $in, $hasSome, $hasAll | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: tags.privateTags.tagIds | operators: $eq, $ne, $exists, $in, $hasSome, $hasAll | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
 Return type: PROMISE<QueryPromotionsResponse>
  - name: promotions | type: array<Promotion> | description: List of promotions.  
     - name: _id | type: string | description: Promotion GUID.  | validation: format GUID
     - name: revision | type: string | description: Revision number, which increments by 1 each time the promotion is updated. To prevent conflicting changes, the current revision must be passed when updating the promotion.  | validation: format int64
     - name: _createdDate | type: Date | description: Date and time the promotion was created.  
     - name: _updatedDate | type: Date | description: Date and time the promotion was last updated.  
     - name: name | type: string | description: Promotion name.  | validation: minLength 1, maxLength 50
     - name: media | type: PromotionMedia | description: Promotion media.  
        - ONE-OF: 
           - name: _id | type: string | description: Set media by GUID of an existing file in Wix Media Manager.  | validation: minLength 1, maxLength 200
           - name: url | type: string | description: Set media using an external media URL.  When provided, Wix Media Manager imports the media asynchronously. During import: - `image` is empty. - The promotion is saved as disabled regardless of the requested `enabled` value.  Once the import completes successfully, the promotion's `image` is populated and `enabled` is set to the originally requested value. If the import fails, the promotion's entire `media` object is cleared and the promotion stays disabled. To retry, set new media.  | validation: format WEB_URL
        - name: altText | type: string | description: Image alt text.  | validation: minLength 1, maxLength 1000
        - name: displayName | type: string | description: Media display name.  Overrides the default media name. Can be passed only when the media is set by a URL in this item's `url` field.  | validation: maxLength 80
        - name: mediaType | type: MediaType | description: Media type.  
             - enum:
             -     IMAGE: Image media type.
        - name: uploadId | type: string | description: GUID of the asynchronous media import that Wix Media Manager runs when media is set with a `url`.  | validation: format GUID
     - name: destinationUrl | type: string | description: URL the promotion redirects to when a customer clicks the banner.  | validation: format WEB_URL
     - name: categories | type: array<CategoryAssignment> | description: Categories the promotion is directly assigned to. A promotion may also appear in subcategories when `appliedToSubcategories` is `true` for a directly assigned category.  | validation: maxItems 1000
        - name: _id | type: string | description: Category GUID.  | validation: format GUID
        - name: position | type: integer | description: Position of the promotion within the category, starting from 1.  Must be provided for each category assignment — omitting it fails validation, because positions start from 1.  | validation: minimum 1
        - name: appliedToSubcategories | type: boolean | description: Whether the promotion also appears in this category's subcategories. When inherited by a subcategory, the promotion keeps the same position.  Default: `false`  
     - name: enabled | type: boolean | description: Whether the promotion is enabled.  When creating or updating with `media.url`, this value takes effect only after the media import completes successfully. See `media.url` for details.  Default: `false`  
     - name: extendedFields | type: ExtendedFields | description: Custom field data for the promotion object.  [Extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.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: tags | type: Tags | description: Tags for organizing and filtering promotions.  
        - name: privateTags | type: TagList | description: Tags that require an additional permission in order to access them, normally not given to site members or visitors.  
           - name: tagIds | type: array<string> | description: List of tag GUIDs.  | validation: maxItems 100, maxLength 5
        - name: publicTags | type: TagList | description: Tags that are exposed to anyone who has access to the labeled entity itself, including site members and visitors.  
  - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata.  
     - name: count | type: integer | description: Number of items returned in current page.  | 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 enabled promotions
Retrieves promotions filtered by their enabled state, sorted and paged with the query builder.

```javascript
import { promotionsV3 } from "@wix/stores";

async function queryPromotions() {
  const response = await promotionsV3
    .queryPromotions()
    .eq("enabled", true)
    .descending("_createdDate")
    .limit(10)
    .find();

  return response;
}

/* Promise resolves to (response.items):
 * [
 *   {
 *     "_id": "25fc9c97-1ecf-47a1-9350-5766867d307e",
 *     "revision": "2",
 *     "name": "Summer Sale Banner",
 *     "destinationUrl": "https://www.example.com/summer-sale",
 *     "categories": [],
 *     "enabled": true,
 *     "_createdDate": "2026-07-21T08:01:14.583Z",
 *     "_updatedDate": "2026-07-21T08:01:17.396Z"
 *   }
 * ]
 */

```

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

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


async function queryPromotions(query) {
  const response = await myWixClient.promotionsV3.queryPromotions(query);
};
```

---