> 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

# QueryAchievements

# Package: partnersProgram

# Namespace: PartnersProgramAchievements

# Method link: https://dev.wix.com/docs/api-reference/account-level/studio-workspace/partners-program/achievement-v1/query-achievements.md

## Permission Scopes:
SCOPE.PARTNERS.PARTNERS_PROGRAM_READ: SCOPE.PARTNERS.PARTNERS_PROGRAM_READ

## Introduction

Retrieves a list of up to 200 achievements, given the provided paging, filtering, and sorting.

Results are always scoped to the calling account, which is derived from the request's identity.

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

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

Supported filter and sort fields: `id`, `points`, `achievementType`.

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: queryAchievements
 Description: Retrieves a list of up to 200 achievements, given the provided paging, filtering, and sorting.  Results are always scoped to the calling account, which is derived from the request's identity.  Query Achievements runs with these defaults, which you can override:  - `createdDate` is sorted in `DESC` order - `cursorPaging.limit` is `50`  Supported filter and sort fields: `id`, `points`, `achievementType`.  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/partnersprogram/v1/partners-program/achievements/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 200, 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: Field to sort by.  Supported properties: `id`, `points`, `achievementType`  
           - name: order | type: SortOrder | description: Sort order. Use `ASC` for ascending order or `DESC` for descending order.  Default: `ASC`  
                 - 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: points | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: achievementType | operators: $eq, $ne, $in, $exists | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
 Return type: QueryAchievementsResponse
  - name: achievements | type: array<Achievement> | description: The retrieved achievements.  
     - ONE-OF: 
        - name: manualOptions | type: ManualOptions | description: Details for a manually granted achievement (`achievementType` is `MANUAL`).  
           - name: comment | type: string | description: Optional note describing why the achievement was granted.  
        - name: premiumOptions | type: PremiumOptions | description: Details for a premium-subscription achievement (`achievementType` is `PREMIUM`).  
           - name: metaSiteId | type: string | description: GUID of the site whose premium subscription earned the achievement.  | validation: format GUID
           - name: premiumProductId | type: string | description: GUID of the premium product (from the premium product catalog) that earned the achievement.  | validation: format GUID
           - name: role | type: Role | description: The partner's role on the site that earned the achievement.  
                 - enum:
                 -     OWNER: The partner owns the site.
                 -     CONTRIBUTOR: The partner contributes to a site owned by someone else.
           - name: siteName | type: string | description: Display name of the site that earned the achievement, captured when the achievement was created. May be absent for achievements created before this field was introduced.  | validation: maxLength 500
        - name: migrationOptions | type: MigrationOptions | description: Details for an achievement created during data migration (`achievementType` is `MIGRATION`).  
           - name: loyaltyPoints | type: integer | description: Legacy loyalty points carried over during migration.  
        - name: certificationOptions | type: CertificationOptions | description: Details for a certification achievement (`achievementType` is `CERTIFICATION`).  
           - name: certificationType | type: CertificationType | description: The certification that earned the achievement.  
                 - enum:
                 -     VELO: Maintainer note: this enum (and Role) intentionally has no UNKNOWN/zero sentinel. Every value is exhaustively mapped to a domain enum (CertificationTypeDomain / RoleDomain) by the automapper, which rejects proto values with no domain counterpart. When adding a value, add its domain mapping.
                 -     ACCESSIBILITY: Web accessibility certification.
                 -     WEB_DESIGNER: Wix web design certification.
                 -     STUDIO_DEVELOPER: Wix Studio development certification.
                 -     STUDIO_DESIGN_LEAGUE: Wix Studio Design League certification.
                 -     STUDIO_DEV_WEBSITES_LEAGUE: Wix Studio Developer Websites League certification.
     - name: id | type: string | description: Achievement GUID.  | read-only: true | validation: format GUID
     - name: revision | type: string | description: Revision number, which increments by 1 each time the achievement is updated.  | read-only: true | validation: format int64
     - name: createdDate | type: string | description: Date and time the achievement was created.  | read-only: true | validation: format date-time
     - name: updatedDate | type: string | description: Date and time the achievement was last updated.  | read-only: true | validation: format date-time
     - name: points | type: integer | description: Number of points this achievement contributes toward the partner's program level.  
     - name: achievementType | type: AchievementType | description: How the achievement was earned. Determines which of the `options` details are populated.  
         - enum:
         -     UNKNOWN: Unknown achievement type.
         -     PREMIUM: Awarded for a premium subscription on a site the partner manages.
         -     MANUAL: Granted manually rather than earned through partner activity. The Wix Partners dashboard combines all `MANUAL` and `MIGRATION` achievements into a single entry showing their combined points, but this API returns each achievement individually.
         -     MIGRATION: Created when historical program data was migrated. The Wix Partners dashboard combines all `MANUAL` and `MIGRATION` achievements into a single entry showing their combined points, but this API returns each achievement individually.
         -     CERTIFICATION: Awarded for completing a Wix certification.
  - 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 the calling partner's achievements sorted by points
Retrieves the calling partner's achievements, sorted by points in descending order.

```curl
curl -X POST \
'https://www.wixapis.com/partners/partnersprogram/v1/partners-program/achievements/query' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
  "query": {
    "sort": [
      {
        "fieldName": "points",
        "order": "DESC"
      }
    ],
    "cursorPaging": {
      "limit": 10
    }
  }
}'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.partnersProgram.partnersProgram.queryAchievements(query)
 Description: Retrieves a list of up to 200 achievements, given the provided paging, filtering, and sorting.  Results are always scoped to the calling account, which is derived from the request's identity.  Query Achievements runs with these defaults, which you can override:  - `createdDate` is sorted in `DESC` order - `cursorPaging.limit` is `50`  Supported filter and sort fields: `id`, `points`, `achievementType`.  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: AchievementQuery   | 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 200, 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: Field to sort by.  Supported properties: `id`, `points`, `achievementType`  
           - name: order | type: SortOrder | description: Sort order. Use `ASC` for ascending order or `DESC` for descending order.  Default: `ASC`  
                 - 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: points | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: achievementType | operators: $eq, $ne, $in, $exists | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
 Return type: PROMISE<QueryAchievementsResponse>
  - name: achievements | type: array<Achievement> | description: The retrieved achievements.  
     - ONE-OF: 
        - name: manualOptions | type: ManualOptions | description: Details for a manually granted achievement (`achievementType` is `MANUAL`).  
           - name: comment | type: string | description: Optional note describing why the achievement was granted.  
        - name: premiumOptions | type: PremiumOptions | description: Details for a premium-subscription achievement (`achievementType` is `PREMIUM`).  
           - name: metaSiteId | type: string | description: GUID of the site whose premium subscription earned the achievement.  | validation: format GUID
           - name: premiumProductId | type: string | description: GUID of the premium product (from the premium product catalog) that earned the achievement.  | validation: format GUID
           - name: role | type: Role | description: The partner's role on the site that earned the achievement.  
                 - enum:
                 -     OWNER: The partner owns the site.
                 -     CONTRIBUTOR: The partner contributes to a site owned by someone else.
           - name: siteName | type: string | description: Display name of the site that earned the achievement, captured when the achievement was created. May be absent for achievements created before this field was introduced.  | validation: maxLength 500
        - name: migrationOptions | type: MigrationOptions | description: Details for an achievement created during data migration (`achievementType` is `MIGRATION`).  
           - name: loyaltyPoints | type: integer | description: Legacy loyalty points carried over during migration.  
        - name: certificationOptions | type: CertificationOptions | description: Details for a certification achievement (`achievementType` is `CERTIFICATION`).  
           - name: certificationType | type: CertificationType | description: The certification that earned the achievement.  
                 - enum:
                 -     VELO: Maintainer note: this enum (and Role) intentionally has no UNKNOWN/zero sentinel. Every value is exhaustively mapped to a domain enum (CertificationTypeDomain / RoleDomain) by the automapper, which rejects proto values with no domain counterpart. When adding a value, add its domain mapping.
                 -     ACCESSIBILITY: Web accessibility certification.
                 -     WEB_DESIGNER: Wix web design certification.
                 -     STUDIO_DEVELOPER: Wix Studio development certification.
                 -     STUDIO_DESIGN_LEAGUE: Wix Studio Design League certification.
                 -     STUDIO_DEV_WEBSITES_LEAGUE: Wix Studio Developer Websites League certification.
     - name: _id | type: string | description: Achievement GUID.  | read-only: true | validation: format GUID
     - name: revision | type: string | description: Revision number, which increments by 1 each time the achievement is updated.  | read-only: true | validation: format int64
     - name: _createdDate | type: Date | description: Date and time the achievement was created.  | read-only: true 
     - name: _updatedDate | type: Date | description: Date and time the achievement was last updated.  | read-only: true 
     - name: points | type: integer | description: Number of points this achievement contributes toward the partner's program level.  
     - name: achievementType | type: AchievementType | description: How the achievement was earned. Determines which of the `options` details are populated.  
         - enum:
         -     UNKNOWN: Unknown achievement type.
         -     PREMIUM: Awarded for a premium subscription on a site the partner manages.
         -     MANUAL: Granted manually rather than earned through partner activity. The Wix Partners dashboard combines all `MANUAL` and `MIGRATION` achievements into a single entry showing their combined points, but this API returns each achievement individually.
         -     MIGRATION: Created when historical program data was migrated. The Wix Partners dashboard combines all `MANUAL` and `MIGRATION` achievements into a single entry showing their combined points, but this API returns each achievement individually.
         -     CERTIFICATION: Awarded for completing a Wix certification.
  - 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 the calling partner's achievements sorted by points
```javascript
import { partnersProgram } from "@wix/partners-program";

async function queryAchievements() {
  const response = await partnersProgram.queryAchievements({
    sort: [{ fieldName: "points", order: "DESC" }],
    cursorPaging: { limit: 10 },
  });

  return response;
}

/* Promise resolves to:
 * {
 *   "achievements": [
 *     {
 *       "_id": "d7a341c4-196b-46e7-813c-2b0fc1847ec6",
 *       "revision": "1",
 *       "_createdDate": "2024-01-15T10:30:00.000Z",
 *       "_updatedDate": "2024-01-15T10:30:00.000Z",
 *       "points": 1000,
 *       "achievementType": "PREMIUM",
 *       "premiumOptions": {
 *         "metaSiteId": "b1c2d3e4-5678-4abc-9def-0123456789ab",
 *         "premiumProductId": "a9f8e7d6-4321-4cba-8fed-9876543210fe",
 *         "role": "OWNER",
 *         "siteName": "My Client's Studio Site"
 *       }
 *     },
 *     {
 *       "_id": "f2e4c6a8-0b1d-4e3f-9a5c-6d7e8f901234",
 *       "revision": "1",
 *       "_createdDate": "2024-02-20T14:05:00.000Z",
 *       "_updatedDate": "2024-02-20T14:05:00.000Z",
 *       "points": 500,
 *       "achievementType": "CERTIFICATION",
 *       "certificationOptions": {
 *         "certificationType": "STUDIO_DEVELOPER"
 *       }
 *     }
 *   ],
 *   "pagingMetadata": {
 *     "count": 2,
 *     "cursors": {
 *       "next": "eyJvZmZzZXQiOjEwfQ=="
 *     },
 *     "hasNext": true
 *   }
 * }
 */

```

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

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


async function queryAchievements(query) {
  const response = await myWixClient.partnersProgram.queryAchievements(query);
};
```

---