Merge pull request #87 from clerk/update-openapi-specs-20260212-182811

chore: Update OpenAPI Specs

Author: LauraBeatris

bapi/2021-02-05.yml

@@ -4479,6 +4479,10 @@ paths:
                   type: string
                   description: A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).
                   nullable: true
+                role_set_key:
+                  type: string
+                  description: The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization.
+                  nullable: true
               required:
                 - name
       responses:
@@ -4584,6 +4588,10 @@ paths:
                   type: string
                   description: A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).
                   nullable: true
+                role_set_key:
+                  type: string
+                  description: The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization.
+                  nullable: true
       responses:
         '200':
           $ref: '#/components/responses/Organization'
@@ -6492,6 +6500,10 @@ paths:
                 force_authn:
                   type: boolean
                   description: Enable or deactivate ForceAuthn
+                consent_verified_domains_deletion:
+                  type: boolean
+                  description: When enabling the connection, controls behavior when verified domains used for enrollment modes like automatic invitation or automatic suggestion already exist for the same domain. If true, those verified domains are removed and the connection is enabled. If false or omitted, the request fails when any such verified domain exists.
+                  nullable: true
       responses:
         '200':
           $ref: '#/components/responses/SAMLConnection'
@@ -11173,6 +11185,11 @@ components:
           format: int64
           description: |
             Unix timestamp of last activity.
+        role_set_key:
+          type: string
+          description: |
+            The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) assigned to this organization.
+          nullable: true
       required:
         - object
         - id
@@ -12571,6 +12588,9 @@ components:
         image_url:
           type: string
           description: URL of the payer's image/avatar.
+        credits_balance:
+          $ref: '#/components/schemas/CommerceMoneyResponse'
+          description: Current credits balance for the payer.
         created_at:
           type: integer
           format: int64

bapi/2024-10-01.yml

@@ -4479,6 +4479,10 @@ paths:
                   type: string
                   description: A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).
                   nullable: true
+                role_set_key:
+                  type: string
+                  description: The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization.
+                  nullable: true
               required:
                 - name
       responses:
@@ -4584,6 +4588,10 @@ paths:
                   type: string
                   description: A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).
                   nullable: true
+                role_set_key:
+                  type: string
+                  description: The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization.
+                  nullable: true
       responses:
         '200':
           $ref: '#/components/responses/Organization'
@@ -6765,6 +6773,10 @@ paths:
                 force_authn:
                   type: boolean
                   description: Enable or deactivate ForceAuthn
+                consent_verified_domains_deletion:
+                  type: boolean
+                  description: When enabling the connection, controls behavior when verified domains used for enrollment modes like automatic invitation or automatic suggestion already exist for the same domain. If true, those verified domains are removed and the connection is enabled. If false or omitted, the request fails when any such verified domain exists.
+                  nullable: true
       responses:
         '200':
           $ref: '#/components/responses/SAMLConnection'
@@ -11446,6 +11458,11 @@ components:
           format: int64
           description: |
             Unix timestamp of last activity.
+        role_set_key:
+          type: string
+          description: |
+            The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) assigned to this organization.
+          nullable: true
       required:
         - object
         - id
@@ -12844,6 +12861,9 @@ components:
         image_url:
           type: string
           description: URL of the payer's image/avatar.
+        credits_balance:
+          $ref: '#/components/schemas/CommerceMoneyResponse'
+          description: Current credits balance for the payer.
         created_at:
           type: integer
           format: int64

bapi/2025-04-10.yml

@@ -4470,6 +4470,10 @@ paths:
                   type: string
                   description: A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).
                   nullable: true
+                role_set_key:
+                  type: string
+                  description: The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization.
+                  nullable: true
               required:
                 - name
       responses:
@@ -4575,6 +4579,10 @@ paths:
                   type: string
                   description: A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).
                   nullable: true
+                role_set_key:
+                  type: string
+                  description: The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization.
+                  nullable: true
       responses:
         '200':
           $ref: '#/components/responses/Organization'
@@ -6756,6 +6764,10 @@ paths:
                 force_authn:
                   type: boolean
                   description: Enable or deactivate ForceAuthn
+                consent_verified_domains_deletion:
+                  type: boolean
+                  description: When enabling the connection, controls behavior when verified domains used for enrollment modes like automatic invitation or automatic suggestion already exist for the same domain. If true, those verified domains are removed and the connection is enabled. If false or omitted, the request fails when any such verified domain exists.
+                  nullable: true
       responses:
         '200':
           $ref: '#/components/responses/SAMLConnection'
@@ -11474,6 +11486,11 @@ components:
           format: int64
           description: |
             Unix timestamp of last activity.
+        role_set_key:
+          type: string
+          description: |
+            The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) assigned to this organization.
+          nullable: true
       required:
         - object
         - id
@@ -12147,6 +12164,9 @@ components:
         image_url:
           type: string
           description: URL of the payer's image/avatar.
+        credits_balance:
+          $ref: '#/components/schemas/CommerceMoneyResponse'
+          description: Current credits balance for the payer.
         created_at:
           type: integer
           format: int64

bapi/2025-11-10.yml

@@ -4542,6 +4542,10 @@ paths:
                   type: string
                   description: A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).
                   nullable: true
+                role_set_key:
+                  type: string
+                  description: The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization.
+                  nullable: true
               required:
                 - name
       responses:
@@ -4647,6 +4651,10 @@ paths:
                   type: string
                   description: A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).
                   nullable: true
+                role_set_key:
+                  type: string
+                  description: The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization.
+                  nullable: true
       responses:
         '200':
           $ref: '#/components/responses/Organization'
@@ -6828,6 +6836,10 @@ paths:
                 force_authn:
                   type: boolean
                   description: Enable or deactivate ForceAuthn
+                consent_verified_domains_deletion:
+                  type: boolean
+                  description: When enabling the connection, controls behavior when verified domains used for enrollment modes like automatic invitation or automatic suggestion already exist for the same domain. If true, those verified domains are removed and the connection is enabled. If false or omitted, the request fails when any such verified domain exists.
+                  nullable: true
       responses:
         '200':
           $ref: '#/components/responses/SAMLConnection'
@@ -11736,6 +11748,11 @@ components:
           format: int64
           description: |
             Unix timestamp of last activity.
+        role_set_key:
+          type: string
+          description: |
+            The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) assigned to this organization.
+          nullable: true
       required:
         - object
         - id
@@ -12371,6 +12388,9 @@ components:
         image_url:
           type: string
           description: URL of the payer's image/avatar.
+        credits_balance:
+          $ref: '#/components/schemas/CommerceMoneyResponse'
+          description: Current credits balance for the payer.
         created_at:
           type: integer
           format: int64
@@ -14582,6 +14602,9 @@ components:
         image_url:
           type: string
           description: URL of the payer's image/avatar.
+        credits_balance:
+          $ref: '#/components/schemas/CommerceMoneyResponse'
+          description: Current credits balance for the payer.
         created_at:
           type: integer
           format: int64

fapi/2025-11-10.yml

@@ -11509,6 +11509,9 @@ components:
           type: string
           format: uri
           description: URL of the payer's image/avatar
+        credits_balance:
+          $ref: '#/components/schemas/BillingMoneyResponse'
+          description: Current credits balance for the payer
         created_at:
           type: integer
           format: int64
@@ -11854,6 +11857,66 @@ components:
       required:
         - response
         - client
+    BillingProrationCreditDetail:
+      type: object
+      additionalProperties: false
+      properties:
+        amount:
+          $ref: '#/components/schemas/BillingMoneyResponse'
+          description: Credit amount with formatting
+        cycle_days_remaining:
+          type: integer
+          format: int64
+          description: Number of days remaining in the billing cycle
+        cycle_days_total:
+          type: integer
+          format: int64
+          description: Total number of days in the billing cycle
+        cycle_remaining_percent:
+          type: number
+          format: double
+          description: Percentage of the billing cycle remaining
+      required:
+        - amount
+        - cycle_days_remaining
+        - cycle_days_total
+        - cycle_remaining_percent
+    BillingPayerCreditResponse:
+      type: object
+      additionalProperties: false
+      properties:
+        remaining_balance:
+          $ref: '#/components/schemas/BillingMoneyResponse'
+          description: The payer's remaining credit balance after credit is applied for this checkout (in cents)
+        applied_amount:
+          $ref: '#/components/schemas/BillingMoneyResponse'
+          description: The amount of payer credit applied to this checkout (in cents)
+      required:
+        - remaining_balance
+        - applied_amount
+    BillingCreditsResponse:
+      type: object
+      additionalProperties: false
+      properties:
+        proration:
+          type: object
+          nullable: true
+          allOf:
+            - $ref: '#/components/schemas/BillingProrationCreditDetail'
+          description: Proration credit details from unused subscription time
+        payer:
+          type: object
+          nullable: true
+          allOf:
+            - $ref: '#/components/schemas/BillingPayerCreditResponse'
+          description: Payer credit details from the payer's credit balance
+        total:
+          $ref: '#/components/schemas/BillingMoneyResponse'
+          description: Total credits applied
+      required:
+        - proration
+        - payer
+        - total
     BillingCheckoutTotals:
       type: object
       additionalProperties: false
@@ -11891,12 +11954,19 @@ components:
           allOf:
             - $ref: '#/components/schemas/BillingMoneyResponse'
           description: The amount of credit that will be consumed before the payment method is charged
+        credits:
+          type: object
+          nullable: true
+          allOf:
+            - $ref: '#/components/schemas/BillingCreditsResponse'
+          description: Unified credits breakdown
       required:
         - subtotal
         - tax_total
         - grand_total
         - total_due_after_free_trial
         - credit
+        - credits
         - total_due_now
     BillingCheckout:
       type: object

webhooks/2025-04-15.yml

@@ -1997,6 +1997,11 @@ components:
           format: int64
           description: |
             Unix timestamp of last activity.
+        role_set_key:
+          type: string
+          description: |
+            The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) assigned to this organization.
+          nullable: true
       required:
         - object
         - id