From 36336524b3e47086354fcba32e569769c775f3aa Mon Sep 17 00:00:00 2001
From: mario-jerkovic <mario@toming.energy>
Date: Tue, 4 Nov 2025 10:11:53 +0100
Subject: [PATCH 1/2] feat(backend): add `orderBy` support to
 InvitationAPI.getInvitationList

- introduce `orderBy` argument with +/- sign support for sort direction
---
 .changeset/nasty-insects-follow.md            |  5 +++++
 .../src/api/endpoints/InvitationApi.ts        | 21 +++++++++++++++++++
 2 files changed, 26 insertions(+)
 create mode 100644 .changeset/nasty-insects-follow.md

diff --git a/.changeset/nasty-insects-follow.md b/.changeset/nasty-insects-follow.md
new file mode 100644
index 00000000000..4d2fb25d129
--- /dev/null
+++ b/.changeset/nasty-insects-follow.md
@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+feat: add `orderBy` argument to `getInvitationList` to control sorting (supports leading '+' for ascending and '-' for descending)
diff --git a/packages/backend/src/api/endpoints/InvitationApi.ts b/packages/backend/src/api/endpoints/InvitationApi.ts
index f869234ec99..1f9c27276f0 100644
--- a/packages/backend/src/api/endpoints/InvitationApi.ts
+++ b/packages/backend/src/api/endpoints/InvitationApi.ts
@@ -5,6 +5,7 @@ import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { InvitationStatus } from '../resources/Enums';
 import type { Invitation } from '../resources/Invitation';
 import { AbstractAPI } from './AbstractApi';
+import type { WithSign } from './util-types';
 
 const basePath = '/invitations';
 
@@ -23,6 +24,26 @@ type CreateParams = {
 type CreateBulkParams = Array<CreateParams>;
 
 type GetInvitationListParams = ClerkPaginationRequest<{
+  /**
+   * Orders the returned invitations by a specific field and direction.
+   *
+   * Use a leading '-' for descending order, or no sign/'+' for ascending.
+   *
+   * Supported fields:
+   * - 'created_at' — when the invitation was created
+   * - 'email_address' — recipient email address
+   * - 'expires_at' — when the invitation expires
+   *
+   * @example:
+   * ```ts
+   * // Newest first
+   * await clerkClient.invitations.getInvitationList({ orderBy: '-created_at' });
+   *
+   * // Alphabetical by email
+   * await clerkClient.invitations.getInvitationList({ orderBy: 'email_address' });
+   * ```
+   */
+  orderBy?: WithSign<'created_at' | 'email_address' | 'expires_at'>;
   /**
    * Filters invitations based on their status.
    *

From 3831714ff2811f3573f698f641770d766f2a1655 Mon Sep 17 00:00:00 2001
From: mario-jerkovic <mario@toming.energy>
Date: Tue, 4 Nov 2025 10:20:22 +0100
Subject: [PATCH 2/2] style(backend): change JSDocs using standard syntax

---
 packages/backend/src/api/endpoints/InvitationApi.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/backend/src/api/endpoints/InvitationApi.ts b/packages/backend/src/api/endpoints/InvitationApi.ts
index 1f9c27276f0..d852737e848 100644
--- a/packages/backend/src/api/endpoints/InvitationApi.ts
+++ b/packages/backend/src/api/endpoints/InvitationApi.ts
@@ -34,7 +34,7 @@ type GetInvitationListParams = ClerkPaginationRequest<{
    * - 'email_address' — recipient email address
    * - 'expires_at' — when the invitation expires
    *
-   * @example:
+   * @example
    * ```ts
    * // Newest first
    * await clerkClient.invitations.getInvitationList({ orderBy: '-created_at' });