From 81dd1c54dc093b3ab0e10d279f8bf585dbc673d9 Mon Sep 17 00:00:00 2001 From: Clerk Bot Date: Fri, 14 Aug 2026 17:34:08 +0000 Subject: [PATCH] chore: Update OpenAPI Specs --- bapi/2021-02-05.yml | 194 ++++++++++++++++++++++++++++++++++ bapi/2024-10-01.yml | 194 ++++++++++++++++++++++++++++++++++ bapi/2025-04-10.yml | 194 ++++++++++++++++++++++++++++++++++ bapi/2025-11-10.yml | 198 +++++++++++++++++++++++++++++++++- bapi/2026-05-12.yml | 198 +++++++++++++++++++++++++++++++++- fapi/2021-02-05.yml | 4 + fapi/2024-10-01.yml | 4 + fapi/2025-04-10.yml | 4 + fapi/2025-11-10.yml | 252 ++++++++++++++++++++++++++++++++++++++++++++ fapi/2026-05-12.yml | 252 ++++++++++++++++++++++++++++++++++++++++++++ 10 files changed, 1490 insertions(+), 4 deletions(-) diff --git a/bapi/2021-02-05.yml b/bapi/2021-02-05.yml index cb12fe4..47e8714 100644 --- a/bapi/2021-02-05.yml +++ b/bapi/2021-02-05.yml @@ -8740,6 +8740,91 @@ paths: $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/ClerkErrors' + /billing/subscription_items/{subscription_item_id}/discounts: + post: + operationId: ApplyBillingSubscriptionItemDiscount + x-speakeasy-group: billing + x-speakeasy-name-override: applySubscriptionItemDiscount + tags: + - Billing + summary: Apply a discount to a subscription item + description: |- + Applies an existing discount to a subscription item. + Manual application is an override path: self-serve distribution rules are not enforced. + At most one active discount is allowed per subscription item; applying a different + discount replaces the currently active one. Re-applying the same active discount returns a conflict. + parameters: + - name: subscription_item_id + in: path + description: The ID of the subscription item to apply the discount to + required: true + schema: + type: string + requestBody: + description: Parameters for applying the discount + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ApplyCommerceDiscountRequest' + responses: + '200': + $ref: '#/components/responses/CommerceDiscountRedemption' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableEntity' + '500': + $ref: '#/components/responses/ClerkErrors' + /billing/subscription_items/{subscription_item_id}/discounts/{discount_id}: + delete: + operationId: RemoveBillingSubscriptionItemDiscount + x-speakeasy-group: billing + x-speakeasy-name-override: removeSubscriptionItemDiscount + tags: + - Billing + summary: Remove a discount from a subscription item + description: |- + Removes the active discount from a subscription item. + The discount_id must match the subscription item's currently active discount. + parameters: + - name: subscription_item_id + in: path + description: The ID of the subscription item to remove the discount from + required: true + schema: + type: string + - name: discount_id + in: path + description: The ID of the discount to remove + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/CommerceDiscountRedemption' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableEntity' + '500': + $ref: '#/components/responses/ClerkErrors' /organization_permissions: get: operationId: ListOrganizationPermissions @@ -14434,11 +14519,17 @@ components: example: - http://localhost:3000 - https://some-domain + workspace_id: + type: string + nullable: true + description: The ID of the Clerk workspace that owns the instance's application. It is null when the application has no owner. + example: org_2abc123def456 required: - object - id - environment_type - allowed_origins + - workspace_id InstanceRestrictions: type: object properties: @@ -16807,6 +16898,103 @@ components: $ref: '#/components/schemas/CommerceSubscriptionItem' transition: $ref: '#/components/schemas/CommercePriceTransitionDetails' + ApplyCommerceDiscountRequest: + type: object + additionalProperties: false + required: + - discount_id + properties: + discount_id: + type: string + description: The ID of the discount to apply to the subscription item. + CommerceDiscountRedemptionResponse: + type: object + additionalProperties: false + required: + - object + - id + - subscription_item_id + - discount_id + - source + - cycles_applied + - cycles_remaining + - redeemed_at + - redeemed_by + properties: + object: + type: string + description: String representing the object's type. Objects of the same type share the same value. + enum: + - commerce_discount_redemption + id: + type: string + description: Unique identifier for the discount redemption. + subscription_item_id: + type: string + description: Unique identifier for the subscription item the discount was applied to. + discount_id: + type: string + description: Unique identifier for the discount that was applied. + name: + type: string + description: The display name of the discount. + source: + type: string + description: How the discount was applied to the subscription item. + enum: + - promotion + - manual + - promo_code + promo_code: + type: string + description: The promo code used to redeem the discount, when applicable. + effect: + type: string + description: The snapshotted discount effect. + enum: + - percentage + - fixed_amount + percent_off: + type: number + format: double + nullable: true + description: Percent off when the effect is percentage. + amount_off: + allOf: + - $ref: '#/components/schemas/CommerceMoneyResponse' + nullable: true + description: Fixed amount off when the effect is fixed_amount. + amount: + allOf: + - $ref: '#/components/schemas/CommerceMoneyResponse' + nullable: true + description: |- + How much this discount takes off the subscription item's next renewal charge. + Present for either effect when next-payment data is available. + cycles_remaining: + type: integer + format: int32 + nullable: true + description: Remaining billing cycles the discount applies to. Null means the discount lasts forever. + cycles_applied: + type: integer + format: int32 + description: Number of billing cycles the discount has already been applied to. + status: + type: string + description: Current status of the discount redemption. + enum: + - active + - exhausted + - removed + redeemed_at: + type: integer + format: int64 + description: Unix timestamp (in milliseconds) when the discount was redeemed. + redeemed_by: + type: string + nullable: true + description: Identifier of the actor that redeemed the discount, when available. Permission: type: object properties: @@ -17769,6 +17957,12 @@ components: application/json: schema: $ref: '#/components/schemas/CommercePriceTransitionResponse' + CommerceDiscountRedemption: + description: A commerce discount redemption. + content: + application/json: + schema: + $ref: '#/components/schemas/CommerceDiscountRedemptionResponse' Permissions: description: Success content: diff --git a/bapi/2024-10-01.yml b/bapi/2024-10-01.yml index 79f49f7..e1646ca 100644 --- a/bapi/2024-10-01.yml +++ b/bapi/2024-10-01.yml @@ -9013,6 +9013,91 @@ paths: $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/ClerkErrors' + /billing/subscription_items/{subscription_item_id}/discounts: + post: + operationId: ApplyBillingSubscriptionItemDiscount + x-speakeasy-group: billing + x-speakeasy-name-override: applySubscriptionItemDiscount + tags: + - Billing + summary: Apply a discount to a subscription item + description: |- + Applies an existing discount to a subscription item. + Manual application is an override path: self-serve distribution rules are not enforced. + At most one active discount is allowed per subscription item; applying a different + discount replaces the currently active one. Re-applying the same active discount returns a conflict. + parameters: + - name: subscription_item_id + in: path + description: The ID of the subscription item to apply the discount to + required: true + schema: + type: string + requestBody: + description: Parameters for applying the discount + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ApplyCommerceDiscountRequest' + responses: + '200': + $ref: '#/components/responses/CommerceDiscountRedemption' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableEntity' + '500': + $ref: '#/components/responses/ClerkErrors' + /billing/subscription_items/{subscription_item_id}/discounts/{discount_id}: + delete: + operationId: RemoveBillingSubscriptionItemDiscount + x-speakeasy-group: billing + x-speakeasy-name-override: removeSubscriptionItemDiscount + tags: + - Billing + summary: Remove a discount from a subscription item + description: |- + Removes the active discount from a subscription item. + The discount_id must match the subscription item's currently active discount. + parameters: + - name: subscription_item_id + in: path + description: The ID of the subscription item to remove the discount from + required: true + schema: + type: string + - name: discount_id + in: path + description: The ID of the discount to remove + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/CommerceDiscountRedemption' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableEntity' + '500': + $ref: '#/components/responses/ClerkErrors' /organization_permissions: get: operationId: ListOrganizationPermissions @@ -14707,11 +14792,17 @@ components: example: - http://localhost:3000 - https://some-domain + workspace_id: + type: string + nullable: true + description: The ID of the Clerk workspace that owns the instance's application. It is null when the application has no owner. + example: org_2abc123def456 required: - object - id - environment_type - allowed_origins + - workspace_id InstanceRestrictions: type: object properties: @@ -17176,6 +17267,103 @@ components: $ref: '#/components/schemas/CommerceSubscriptionItem' transition: $ref: '#/components/schemas/CommercePriceTransitionDetails' + ApplyCommerceDiscountRequest: + type: object + additionalProperties: false + required: + - discount_id + properties: + discount_id: + type: string + description: The ID of the discount to apply to the subscription item. + CommerceDiscountRedemptionResponse: + type: object + additionalProperties: false + required: + - object + - id + - subscription_item_id + - discount_id + - source + - cycles_applied + - cycles_remaining + - redeemed_at + - redeemed_by + properties: + object: + type: string + description: String representing the object's type. Objects of the same type share the same value. + enum: + - commerce_discount_redemption + id: + type: string + description: Unique identifier for the discount redemption. + subscription_item_id: + type: string + description: Unique identifier for the subscription item the discount was applied to. + discount_id: + type: string + description: Unique identifier for the discount that was applied. + name: + type: string + description: The display name of the discount. + source: + type: string + description: How the discount was applied to the subscription item. + enum: + - promotion + - manual + - promo_code + promo_code: + type: string + description: The promo code used to redeem the discount, when applicable. + effect: + type: string + description: The snapshotted discount effect. + enum: + - percentage + - fixed_amount + percent_off: + type: number + format: double + nullable: true + description: Percent off when the effect is percentage. + amount_off: + allOf: + - $ref: '#/components/schemas/CommerceMoneyResponse' + nullable: true + description: Fixed amount off when the effect is fixed_amount. + amount: + allOf: + - $ref: '#/components/schemas/CommerceMoneyResponse' + nullable: true + description: |- + How much this discount takes off the subscription item's next renewal charge. + Present for either effect when next-payment data is available. + cycles_remaining: + type: integer + format: int32 + nullable: true + description: Remaining billing cycles the discount applies to. Null means the discount lasts forever. + cycles_applied: + type: integer + format: int32 + description: Number of billing cycles the discount has already been applied to. + status: + type: string + description: Current status of the discount redemption. + enum: + - active + - exhausted + - removed + redeemed_at: + type: integer + format: int64 + description: Unix timestamp (in milliseconds) when the discount was redeemed. + redeemed_by: + type: string + nullable: true + description: Identifier of the actor that redeemed the discount, when available. Permissions: type: object additionalProperties: false @@ -18114,6 +18302,12 @@ components: application/json: schema: $ref: '#/components/schemas/CommercePriceTransitionResponse' + CommerceDiscountRedemption: + description: A commerce discount redemption. + content: + application/json: + schema: + $ref: '#/components/schemas/CommerceDiscountRedemptionResponse' Permissions: description: Success content: diff --git a/bapi/2025-04-10.yml b/bapi/2025-04-10.yml index 44d8ca6..9ea871e 100644 --- a/bapi/2025-04-10.yml +++ b/bapi/2025-04-10.yml @@ -9006,6 +9006,91 @@ paths: $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/ClerkErrors' + /billing/subscription_items/{subscription_item_id}/discounts: + post: + operationId: ApplyBillingSubscriptionItemDiscount + x-speakeasy-group: billing + x-speakeasy-name-override: applySubscriptionItemDiscount + tags: + - Billing + summary: Apply a discount to a subscription item + description: |- + Applies an existing discount to a subscription item. + Manual application is an override path: self-serve distribution rules are not enforced. + At most one active discount is allowed per subscription item; applying a different + discount replaces the currently active one. Re-applying the same active discount returns a conflict. + parameters: + - name: subscription_item_id + in: path + description: The ID of the subscription item to apply the discount to + required: true + schema: + type: string + requestBody: + description: Parameters for applying the discount + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ApplyCommerceDiscountRequest' + responses: + '200': + $ref: '#/components/responses/CommerceDiscountRedemption' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableEntity' + '500': + $ref: '#/components/responses/ClerkErrors' + /billing/subscription_items/{subscription_item_id}/discounts/{discount_id}: + delete: + operationId: RemoveBillingSubscriptionItemDiscount + x-speakeasy-group: billing + x-speakeasy-name-override: removeSubscriptionItemDiscount + tags: + - Billing + summary: Remove a discount from a subscription item + description: |- + Removes the active discount from a subscription item. + The discount_id must match the subscription item's currently active discount. + parameters: + - name: subscription_item_id + in: path + description: The ID of the subscription item to remove the discount from + required: true + schema: + type: string + - name: discount_id + in: path + description: The ID of the discount to remove + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/CommerceDiscountRedemption' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableEntity' + '500': + $ref: '#/components/responses/ClerkErrors' /organization_permissions: get: operationId: ListOrganizationPermissions @@ -15434,11 +15519,17 @@ components: example: - http://localhost:3000 - https://some-domain + workspace_id: + type: string + nullable: true + description: The ID of the Clerk workspace that owns the instance's application. It is null when the application has no owner. + example: org_2abc123def456 required: - object - id - environment_type - allowed_origins + - workspace_id InstanceRestrictions: type: object properties: @@ -17182,6 +17273,103 @@ components: $ref: '#/components/schemas/CommerceSubscriptionItem' transition: $ref: '#/components/schemas/CommercePriceTransitionDetails' + ApplyCommerceDiscountRequest: + type: object + additionalProperties: false + required: + - discount_id + properties: + discount_id: + type: string + description: The ID of the discount to apply to the subscription item. + CommerceDiscountRedemptionResponse: + type: object + additionalProperties: false + required: + - object + - id + - subscription_item_id + - discount_id + - source + - cycles_applied + - cycles_remaining + - redeemed_at + - redeemed_by + properties: + object: + type: string + description: String representing the object's type. Objects of the same type share the same value. + enum: + - commerce_discount_redemption + id: + type: string + description: Unique identifier for the discount redemption. + subscription_item_id: + type: string + description: Unique identifier for the subscription item the discount was applied to. + discount_id: + type: string + description: Unique identifier for the discount that was applied. + name: + type: string + description: The display name of the discount. + source: + type: string + description: How the discount was applied to the subscription item. + enum: + - promotion + - manual + - promo_code + promo_code: + type: string + description: The promo code used to redeem the discount, when applicable. + effect: + type: string + description: The snapshotted discount effect. + enum: + - percentage + - fixed_amount + percent_off: + type: number + format: double + nullable: true + description: Percent off when the effect is percentage. + amount_off: + allOf: + - $ref: '#/components/schemas/CommerceMoneyResponse' + nullable: true + description: Fixed amount off when the effect is fixed_amount. + amount: + allOf: + - $ref: '#/components/schemas/CommerceMoneyResponse' + nullable: true + description: |- + How much this discount takes off the subscription item's next renewal charge. + Present for either effect when next-payment data is available. + cycles_remaining: + type: integer + format: int32 + nullable: true + description: Remaining billing cycles the discount applies to. Null means the discount lasts forever. + cycles_applied: + type: integer + format: int32 + description: Number of billing cycles the discount has already been applied to. + status: + type: string + description: Current status of the discount redemption. + enum: + - active + - exhausted + - removed + redeemed_at: + type: integer + format: int64 + description: Unix timestamp (in milliseconds) when the discount was redeemed. + redeemed_by: + type: string + nullable: true + description: Identifier of the actor that redeemed the discount, when available. Permissions: type: object additionalProperties: false @@ -18120,6 +18308,12 @@ components: application/json: schema: $ref: '#/components/schemas/CommercePriceTransitionResponse' + CommerceDiscountRedemption: + description: A commerce discount redemption. + content: + application/json: + schema: + $ref: '#/components/schemas/CommerceDiscountRedemptionResponse' Permissions: description: Success content: diff --git a/bapi/2025-11-10.yml b/bapi/2025-11-10.yml index 8d71515..ca846d9 100644 --- a/bapi/2025-11-10.yml +++ b/bapi/2025-11-10.yml @@ -9280,6 +9280,91 @@ paths: $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/ClerkErrors' + /billing/subscription_items/{subscription_item_id}/discounts: + post: + operationId: ApplyBillingSubscriptionItemDiscount + x-speakeasy-group: billing + x-speakeasy-name-override: applySubscriptionItemDiscount + tags: + - Billing + summary: Apply a discount to a subscription item + description: |- + Applies an existing discount to a subscription item. + Manual application is an override path: self-serve distribution rules are not enforced. + At most one active discount is allowed per subscription item; applying a different + discount replaces the currently active one. Re-applying the same active discount returns a conflict. + parameters: + - name: subscription_item_id + in: path + description: The ID of the subscription item to apply the discount to + required: true + schema: + type: string + requestBody: + description: Parameters for applying the discount + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ApplyCommerceDiscountRequest' + responses: + '200': + $ref: '#/components/responses/CommerceDiscountRedemption' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableEntity' + '500': + $ref: '#/components/responses/ClerkErrors' + /billing/subscription_items/{subscription_item_id}/discounts/{discount_id}: + delete: + operationId: RemoveBillingSubscriptionItemDiscount + x-speakeasy-group: billing + x-speakeasy-name-override: removeSubscriptionItemDiscount + tags: + - Billing + summary: Remove a discount from a subscription item + description: |- + Removes the active discount from a subscription item. + The discount_id must match the subscription item's currently active discount. + parameters: + - name: subscription_item_id + in: path + description: The ID of the subscription item to remove the discount from + required: true + schema: + type: string + - name: discount_id + in: path + description: The ID of the discount to remove + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/CommerceDiscountRedemption' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableEntity' + '500': + $ref: '#/components/responses/ClerkErrors' /billing/statements: get: operationId: GetBillingStatementList @@ -16291,11 +16376,17 @@ components: example: - http://localhost:3000 - https://some-domain + workspace_id: + type: string + nullable: true + description: The ID of the Clerk workspace that owns the instance's application. It is null when the application has no owner. + example: org_2abc123def456 required: - object - id - environment_type - allowed_origins + - workspace_id InstanceRestrictions: type: object properties: @@ -17995,12 +18086,12 @@ components: type: integer format: int64 nullable: true - description: The monthly amount in cents. Must be at least $1 (100 cents) if not null. + description: The monthly amount in cents. Use `0` for a complimentary price. Positive amounts must be at least $1 (100 cents). annual_monthly_amount: type: integer format: int64 nullable: true - description: The monthly amount in cents when billed annually. Must be at least $1 (100 cents) if not null. + description: The monthly amount in cents when billed annually. Use `0` for a complimentary price. Positive amounts must be at least $1 (100 cents). description: type: string description: An optional description for this custom price. @@ -18557,6 +18648,103 @@ components: $ref: '#/components/schemas/CommerceSubscriptionItem-2' transition: $ref: '#/components/schemas/CommercePriceTransitionDetails' + ApplyCommerceDiscountRequest: + type: object + additionalProperties: false + required: + - discount_id + properties: + discount_id: + type: string + description: The ID of the discount to apply to the subscription item. + CommerceDiscountRedemptionResponse: + type: object + additionalProperties: false + required: + - object + - id + - subscription_item_id + - discount_id + - source + - cycles_applied + - cycles_remaining + - redeemed_at + - redeemed_by + properties: + object: + type: string + description: String representing the object's type. Objects of the same type share the same value. + enum: + - commerce_discount_redemption + id: + type: string + description: Unique identifier for the discount redemption. + subscription_item_id: + type: string + description: Unique identifier for the subscription item the discount was applied to. + discount_id: + type: string + description: Unique identifier for the discount that was applied. + name: + type: string + description: The display name of the discount. + source: + type: string + description: How the discount was applied to the subscription item. + enum: + - promotion + - manual + - promo_code + promo_code: + type: string + description: The promo code used to redeem the discount, when applicable. + effect: + type: string + description: The snapshotted discount effect. + enum: + - percentage + - fixed_amount + percent_off: + type: number + format: double + nullable: true + description: Percent off when the effect is percentage. + amount_off: + allOf: + - $ref: '#/components/schemas/CommerceMoneyResponse' + nullable: true + description: Fixed amount off when the effect is fixed_amount. + amount: + allOf: + - $ref: '#/components/schemas/CommerceMoneyResponse' + nullable: true + description: |- + How much this discount takes off the subscription item's next renewal charge. + Present for either effect when next-payment data is available. + cycles_remaining: + type: integer + format: int32 + nullable: true + description: Remaining billing cycles the discount applies to. Null means the discount lasts forever. + cycles_applied: + type: integer + format: int32 + description: Number of billing cycles the discount has already been applied to. + status: + type: string + description: Current status of the discount redemption. + enum: + - active + - exhausted + - removed + redeemed_at: + type: integer + format: int64 + description: Unix timestamp (in milliseconds) when the discount was redeemed. + redeemed_by: + type: string + nullable: true + description: Identifier of the actor that redeemed the discount, when available. BillingPaymentAttempt: type: object additionalProperties: false @@ -19926,6 +20114,12 @@ components: application/json: schema: $ref: '#/components/schemas/CommercePriceTransitionResponse' + CommerceDiscountRedemption: + description: A commerce discount redemption. + content: + application/json: + schema: + $ref: '#/components/schemas/CommerceDiscountRedemptionResponse' BillingStatement.List: description: A list of billing statements. content: diff --git a/bapi/2026-05-12.yml b/bapi/2026-05-12.yml index 6fe0ae0..e063b20 100644 --- a/bapi/2026-05-12.yml +++ b/bapi/2026-05-12.yml @@ -9231,6 +9231,91 @@ paths: $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/ClerkErrors' + /billing/subscription_items/{subscription_item_id}/discounts: + post: + operationId: ApplyBillingSubscriptionItemDiscount + x-speakeasy-group: billing + x-speakeasy-name-override: applySubscriptionItemDiscount + tags: + - Billing + summary: Apply a discount to a subscription item + description: |- + Applies an existing discount to a subscription item. + Manual application is an override path: self-serve distribution rules are not enforced. + At most one active discount is allowed per subscription item; applying a different + discount replaces the currently active one. Re-applying the same active discount returns a conflict. + parameters: + - name: subscription_item_id + in: path + description: The ID of the subscription item to apply the discount to + required: true + schema: + type: string + requestBody: + description: Parameters for applying the discount + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ApplyCommerceDiscountRequest' + responses: + '200': + $ref: '#/components/responses/CommerceDiscountRedemption' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableEntity' + '500': + $ref: '#/components/responses/ClerkErrors' + /billing/subscription_items/{subscription_item_id}/discounts/{discount_id}: + delete: + operationId: RemoveBillingSubscriptionItemDiscount + x-speakeasy-group: billing + x-speakeasy-name-override: removeSubscriptionItemDiscount + tags: + - Billing + summary: Remove a discount from a subscription item + description: |- + Removes the active discount from a subscription item. + The discount_id must match the subscription item's currently active discount. + parameters: + - name: subscription_item_id + in: path + description: The ID of the subscription item to remove the discount from + required: true + schema: + type: string + - name: discount_id + in: path + description: The ID of the discount to remove + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/CommerceDiscountRedemption' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableEntity' + '500': + $ref: '#/components/responses/ClerkErrors' /billing/statements: get: operationId: GetBillingStatementList @@ -16648,11 +16733,17 @@ components: example: - http://localhost:3000 - https://some-domain + workspace_id: + type: string + nullable: true + description: The ID of the Clerk workspace that owns the instance's application. It is null when the application has no owner. + example: org_2abc123def456 required: - object - id - environment_type - allowed_origins + - workspace_id InstanceRestrictions: type: object properties: @@ -18352,12 +18443,12 @@ components: type: integer format: int64 nullable: true - description: The monthly amount in cents. Must be at least $1 (100 cents) if not null. + description: The monthly amount in cents. Use `0` for a complimentary price. Positive amounts must be at least $1 (100 cents). annual_monthly_amount: type: integer format: int64 nullable: true - description: The monthly amount in cents when billed annually. Must be at least $1 (100 cents) if not null. + description: The monthly amount in cents when billed annually. Use `0` for a complimentary price. Positive amounts must be at least $1 (100 cents). description: type: string description: An optional description for this custom price. @@ -18914,6 +19005,103 @@ components: $ref: '#/components/schemas/CommerceSubscriptionItem-2' transition: $ref: '#/components/schemas/CommercePriceTransitionDetails' + ApplyCommerceDiscountRequest: + type: object + additionalProperties: false + required: + - discount_id + properties: + discount_id: + type: string + description: The ID of the discount to apply to the subscription item. + CommerceDiscountRedemptionResponse: + type: object + additionalProperties: false + required: + - object + - id + - subscription_item_id + - discount_id + - source + - cycles_applied + - cycles_remaining + - redeemed_at + - redeemed_by + properties: + object: + type: string + description: String representing the object's type. Objects of the same type share the same value. + enum: + - commerce_discount_redemption + id: + type: string + description: Unique identifier for the discount redemption. + subscription_item_id: + type: string + description: Unique identifier for the subscription item the discount was applied to. + discount_id: + type: string + description: Unique identifier for the discount that was applied. + name: + type: string + description: The display name of the discount. + source: + type: string + description: How the discount was applied to the subscription item. + enum: + - promotion + - manual + - promo_code + promo_code: + type: string + description: The promo code used to redeem the discount, when applicable. + effect: + type: string + description: The snapshotted discount effect. + enum: + - percentage + - fixed_amount + percent_off: + type: number + format: double + nullable: true + description: Percent off when the effect is percentage. + amount_off: + allOf: + - $ref: '#/components/schemas/CommerceMoneyResponse' + nullable: true + description: Fixed amount off when the effect is fixed_amount. + amount: + allOf: + - $ref: '#/components/schemas/CommerceMoneyResponse' + nullable: true + description: |- + How much this discount takes off the subscription item's next renewal charge. + Present for either effect when next-payment data is available. + cycles_remaining: + type: integer + format: int32 + nullable: true + description: Remaining billing cycles the discount applies to. Null means the discount lasts forever. + cycles_applied: + type: integer + format: int32 + description: Number of billing cycles the discount has already been applied to. + status: + type: string + description: Current status of the discount redemption. + enum: + - active + - exhausted + - removed + redeemed_at: + type: integer + format: int64 + description: Unix timestamp (in milliseconds) when the discount was redeemed. + redeemed_by: + type: string + nullable: true + description: Identifier of the actor that redeemed the discount, when available. BillingPaymentAttempt: type: object additionalProperties: false @@ -20401,6 +20589,12 @@ components: application/json: schema: $ref: '#/components/schemas/CommercePriceTransitionResponse' + CommerceDiscountRedemption: + description: A commerce discount redemption. + content: + application/json: + schema: + $ref: '#/components/schemas/CommerceDiscountRedemptionResponse' BillingStatement.List: description: A list of billing statements. content: diff --git a/fapi/2021-02-05.yml b/fapi/2021-02-05.yml index eea3285..aefe346 100644 --- a/fapi/2021-02-05.yml +++ b/fapi/2021-02-05.yml @@ -8249,6 +8249,9 @@ components: type: string waitlist_url: type: string + oauth_consent_url: + type: string + description: URL of the OAuth consent screen for flows that require human consent. after_sign_in_url: type: string after_sign_up_url: @@ -8355,6 +8358,7 @@ components: - sign_up_url - user_profile_url - waitlist_url + - oauth_consent_url - after_sign_in_url - after_sign_up_url - after_sign_out_one_url diff --git a/fapi/2024-10-01.yml b/fapi/2024-10-01.yml index fa400a0..8b6fef4 100644 --- a/fapi/2024-10-01.yml +++ b/fapi/2024-10-01.yml @@ -7369,6 +7369,9 @@ components: type: string waitlist_url: type: string + oauth_consent_url: + type: string + description: URL of the OAuth consent screen for flows that require human consent. after_sign_in_url: type: string after_sign_up_url: @@ -7475,6 +7478,7 @@ components: - sign_up_url - user_profile_url - waitlist_url + - oauth_consent_url - after_sign_in_url - after_sign_up_url - after_sign_out_one_url diff --git a/fapi/2025-04-10.yml b/fapi/2025-04-10.yml index f8cb45b..d80f51d 100644 --- a/fapi/2025-04-10.yml +++ b/fapi/2025-04-10.yml @@ -7713,6 +7713,9 @@ components: type: string waitlist_url: type: string + oauth_consent_url: + type: string + description: URL of the OAuth consent screen for flows that require human consent. after_sign_in_url: type: string after_sign_up_url: @@ -7819,6 +7822,7 @@ components: - sign_up_url - user_profile_url - waitlist_url + - oauth_consent_url - after_sign_in_url - after_sign_up_url - after_sign_out_one_url diff --git a/fapi/2025-11-10.yml b/fapi/2025-11-10.yml index 6912715..eb3164e 100644 --- a/fapi/2025-11-10.yml +++ b/fapi/2025-11-10.yml @@ -5414,6 +5414,51 @@ paths: $ref: '#/components/responses/ResourceNotFound' '410': $ref: '#/components/responses/ClerkErrors' + patch: + operationId: UpdateUserBillingCheckout + x-speakeasy-group: billing + x-speakeasy-name-override: updateUserCheckout + tags: + - Checkouts + summary: Update billing checkout + description: |- + Applies or removes a promo code on an in-progress billing checkout for the current user. + A non-blank promo_code applies the code; a blank value clears it. + parameters: + - name: checkoutID + in: path + description: The ID of the checkout to update + required: true + schema: + type: string + requestBody: + required: true + content: + application/x-www-form-urlencoded: + schema: + type: object + required: + - promo_code + properties: + promo_code: + type: string + nullable: true + description: |- + The promo code to apply to this checkout. + Send a blank value to clear the currently applied promo code. + responses: + '200': + $ref: '#/components/responses/Client.BillingCheckout' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '409': + $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/UnprocessableEntity' /v1/me/billing/checkouts/{checkoutID}/confirm: patch: operationId: ConfirmUserBillingCheckout @@ -5673,6 +5718,59 @@ paths: $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/UnprocessableEntity' + patch: + operationId: UpdateOrganizationBillingCheckout + x-speakeasy-group: billing + x-speakeasy-name-override: updateOrganizationCheckout + tags: + - Checkouts + summary: Update organization billing checkout + description: |- + Applies or removes a promo code on an in-progress billing checkout for the organization. + A non-blank promo_code applies the code; a blank value clears it. + parameters: + - name: organizationID + in: path + description: The ID of the organization + required: true + schema: + type: string + - name: checkoutID + in: path + description: The ID of the checkout to update + required: true + schema: + type: string + requestBody: + required: true + content: + application/x-www-form-urlencoded: + schema: + type: object + required: + - promo_code + properties: + promo_code: + type: string + nullable: true + description: |- + The promo code to apply to this checkout. + Send a blank value to clear the currently applied promo code. + responses: + '200': + $ref: '#/components/responses/Client.BillingCheckout' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '409': + $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/UnprocessableEntity' /v1/organizations/{organizationID}/billing/checkouts/{checkoutID}/confirm: patch: operationId: ConfirmOrganizationBillingCheckout @@ -11169,6 +11267,9 @@ components: type: string waitlist_url: type: string + oauth_consent_url: + type: string + description: URL of the OAuth consent screen for flows that require human consent. after_sign_in_url: type: string after_sign_up_url: @@ -11275,6 +11376,7 @@ components: - sign_up_url - user_profile_url - waitlist_url + - oauth_consent_url - after_sign_in_url - after_sign_up_url - after_sign_out_one_url @@ -13446,6 +13548,59 @@ components: - cycle_days_passed - cycle_days_total - cycle_passed_percent + BillingAppliedDiscount: + type: object + additionalProperties: false + properties: + amount: + $ref: '#/components/schemas/BillingMoneyResponse' + description: How much this discount takes off the transaction + discount_id: + type: string + description: Unique identifier for the discount + name: + type: string + description: The display name of the discount + effect: + type: string + description: The snapshotted discount effect + enum: + - percentage + - fixed_amount + percent_off: + type: number + format: double + description: Percent off when the effect is percentage + amount_off: + allOf: + - $ref: '#/components/schemas/BillingMoneyResponse' + description: Configured fixed amount off when the effect is fixed_amount + promo_code: + type: string + description: The promo code applied at checkout, when applicable + cycles_remaining: + type: integer + format: int32 + nullable: true + description: Remaining billing cycles the discount applies to. Null means the discount lasts forever + duration_in_cycles: + type: integer + format: int32 + nullable: true + description: Original configured duration in billing cycles. Null means the discount lasts forever + cycles_applied: + type: integer + format: int32 + nullable: true + description: Number of billing cycles the discount has already been applied to + required: + - amount + - discount_id + - name + - effect + - cycles_remaining + - duration_in_cycles + - cycles_applied BillingDiscountsResponse: type: object additionalProperties: false @@ -13456,6 +13611,11 @@ components: allOf: - $ref: '#/components/schemas/BillingProrationDiscountDetail' description: Proration details from passed subscription time + discount: + allOf: + - $ref: '#/components/schemas/BillingAppliedDiscount' + nullable: true + description: Discount applied to this transaction, if any total: $ref: '#/components/schemas/BillingMoneyResponse' description: Total discounts applied @@ -13625,6 +13785,93 @@ components: description: Per-unit cost breakdown by pricing tier required: - quantity + BillingDiscountRedemption: + type: object + additionalProperties: false + properties: + object: + type: string + description: String representing the object's type. Objects of the same type share the same value. + enum: + - commerce_discount_redemption + id: + type: string + description: Unique identifier for the discount redemption + subscription_item_id: + type: string + description: Unique identifier for the subscription item the discount was applied to + discount_id: + type: string + description: Unique identifier for the discount that was applied + name: + type: string + description: The display name of the discount + source: + type: string + description: How the discount was applied to the subscription item + enum: + - manual + - promo_code + promo_code: + type: string + description: The promo code used to redeem the discount, when applicable + effect: + type: string + description: The snapshotted discount effect + enum: + - percentage + - fixed_amount + percent_off: + type: number + format: double + nullable: true + description: Percent off when the effect is percentage + amount_off: + allOf: + - $ref: '#/components/schemas/BillingMoneyResponse' + nullable: true + description: Fixed amount off when the effect is fixed_amount + amount: + allOf: + - $ref: '#/components/schemas/BillingMoneyResponse' + nullable: true + description: |- + How much this discount takes off the subscription item's next renewal charge. + Present for either effect when next-payment data is available. + cycles_remaining: + type: integer + format: int32 + nullable: true + description: Remaining billing cycles the discount applies to. Null means the discount lasts forever + cycles_applied: + type: integer + format: int32 + description: Number of billing cycles the discount has already been applied to + status: + type: string + description: Current status of the discount redemption + enum: + - active + - exhausted + - removed + redeemed_at: + type: integer + format: int64 + description: Unix timestamp (in milliseconds) when the discount was redeemed + redeemed_by: + type: string + nullable: true + description: Identifier of the actor that redeemed the discount, when available + required: + - object + - id + - subscription_item_id + - discount_id + - source + - cycles_applied + - cycles_remaining + - redeemed_at + - redeemed_by BillingSubscriptionItem: type: object additionalProperties: false @@ -13744,6 +13991,11 @@ components: - $ref: '#/components/schemas/BillingTotalsResponse' nullable: true description: Totals for this subscription item + applied_discount: + allOf: + - $ref: '#/components/schemas/BillingDiscountRedemption' + nullable: true + description: The currently active discount applied to this subscription item, if any required: - object - id diff --git a/fapi/2026-05-12.yml b/fapi/2026-05-12.yml index 7708c1b..7c4b6e0 100644 --- a/fapi/2026-05-12.yml +++ b/fapi/2026-05-12.yml @@ -5608,6 +5608,51 @@ paths: $ref: '#/components/responses/ResourceNotFound' '410': $ref: '#/components/responses/ClerkErrors' + patch: + operationId: UpdateUserBillingCheckout + x-speakeasy-group: billing + x-speakeasy-name-override: updateUserCheckout + tags: + - Checkouts + summary: Update billing checkout + description: |- + Applies or removes a promo code on an in-progress billing checkout for the current user. + A non-blank promo_code applies the code; a blank value clears it. + parameters: + - name: checkoutID + in: path + description: The ID of the checkout to update + required: true + schema: + type: string + requestBody: + required: true + content: + application/x-www-form-urlencoded: + schema: + type: object + required: + - promo_code + properties: + promo_code: + type: string + nullable: true + description: |- + The promo code to apply to this checkout. + Send a blank value to clear the currently applied promo code. + responses: + '200': + $ref: '#/components/responses/Client.BillingCheckout' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '409': + $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/UnprocessableEntity' /v1/me/billing/checkouts/{checkoutID}/confirm: patch: operationId: ConfirmUserBillingCheckout @@ -5867,6 +5912,59 @@ paths: $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/UnprocessableEntity' + patch: + operationId: UpdateOrganizationBillingCheckout + x-speakeasy-group: billing + x-speakeasy-name-override: updateOrganizationCheckout + tags: + - Checkouts + summary: Update organization billing checkout + description: |- + Applies or removes a promo code on an in-progress billing checkout for the organization. + A non-blank promo_code applies the code; a blank value clears it. + parameters: + - name: organizationID + in: path + description: The ID of the organization + required: true + schema: + type: string + - name: checkoutID + in: path + description: The ID of the checkout to update + required: true + schema: + type: string + requestBody: + required: true + content: + application/x-www-form-urlencoded: + schema: + type: object + required: + - promo_code + properties: + promo_code: + type: string + nullable: true + description: |- + The promo code to apply to this checkout. + Send a blank value to clear the currently applied promo code. + responses: + '200': + $ref: '#/components/responses/Client.BillingCheckout' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '409': + $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/UnprocessableEntity' /v1/organizations/{organizationID}/billing/checkouts/{checkoutID}/confirm: patch: operationId: ConfirmOrganizationBillingCheckout @@ -11611,6 +11709,9 @@ components: type: string waitlist_url: type: string + oauth_consent_url: + type: string + description: URL of the OAuth consent screen for flows that require human consent. after_sign_in_url: type: string after_sign_up_url: @@ -11717,6 +11818,7 @@ components: - sign_up_url - user_profile_url - waitlist_url + - oauth_consent_url - after_sign_in_url - after_sign_up_url - after_sign_out_one_url @@ -14057,6 +14159,59 @@ components: - cycle_days_passed - cycle_days_total - cycle_passed_percent + BillingAppliedDiscount: + type: object + additionalProperties: false + properties: + amount: + $ref: '#/components/schemas/BillingMoneyResponse' + description: How much this discount takes off the transaction + discount_id: + type: string + description: Unique identifier for the discount + name: + type: string + description: The display name of the discount + effect: + type: string + description: The snapshotted discount effect + enum: + - percentage + - fixed_amount + percent_off: + type: number + format: double + description: Percent off when the effect is percentage + amount_off: + allOf: + - $ref: '#/components/schemas/BillingMoneyResponse' + description: Configured fixed amount off when the effect is fixed_amount + promo_code: + type: string + description: The promo code applied at checkout, when applicable + cycles_remaining: + type: integer + format: int32 + nullable: true + description: Remaining billing cycles the discount applies to. Null means the discount lasts forever + duration_in_cycles: + type: integer + format: int32 + nullable: true + description: Original configured duration in billing cycles. Null means the discount lasts forever + cycles_applied: + type: integer + format: int32 + nullable: true + description: Number of billing cycles the discount has already been applied to + required: + - amount + - discount_id + - name + - effect + - cycles_remaining + - duration_in_cycles + - cycles_applied BillingDiscountsResponse: type: object additionalProperties: false @@ -14067,6 +14222,11 @@ components: allOf: - $ref: '#/components/schemas/BillingProrationDiscountDetail' description: Proration details from passed subscription time + discount: + allOf: + - $ref: '#/components/schemas/BillingAppliedDiscount' + nullable: true + description: Discount applied to this transaction, if any total: $ref: '#/components/schemas/BillingMoneyResponse' description: Total discounts applied @@ -14236,6 +14396,93 @@ components: description: Per-unit cost breakdown by pricing tier required: - quantity + BillingDiscountRedemption: + type: object + additionalProperties: false + properties: + object: + type: string + description: String representing the object's type. Objects of the same type share the same value. + enum: + - commerce_discount_redemption + id: + type: string + description: Unique identifier for the discount redemption + subscription_item_id: + type: string + description: Unique identifier for the subscription item the discount was applied to + discount_id: + type: string + description: Unique identifier for the discount that was applied + name: + type: string + description: The display name of the discount + source: + type: string + description: How the discount was applied to the subscription item + enum: + - manual + - promo_code + promo_code: + type: string + description: The promo code used to redeem the discount, when applicable + effect: + type: string + description: The snapshotted discount effect + enum: + - percentage + - fixed_amount + percent_off: + type: number + format: double + nullable: true + description: Percent off when the effect is percentage + amount_off: + allOf: + - $ref: '#/components/schemas/BillingMoneyResponse' + nullable: true + description: Fixed amount off when the effect is fixed_amount + amount: + allOf: + - $ref: '#/components/schemas/BillingMoneyResponse' + nullable: true + description: |- + How much this discount takes off the subscription item's next renewal charge. + Present for either effect when next-payment data is available. + cycles_remaining: + type: integer + format: int32 + nullable: true + description: Remaining billing cycles the discount applies to. Null means the discount lasts forever + cycles_applied: + type: integer + format: int32 + description: Number of billing cycles the discount has already been applied to + status: + type: string + description: Current status of the discount redemption + enum: + - active + - exhausted + - removed + redeemed_at: + type: integer + format: int64 + description: Unix timestamp (in milliseconds) when the discount was redeemed + redeemed_by: + type: string + nullable: true + description: Identifier of the actor that redeemed the discount, when available + required: + - object + - id + - subscription_item_id + - discount_id + - source + - cycles_applied + - cycles_remaining + - redeemed_at + - redeemed_by BillingSubscriptionItem: type: object additionalProperties: false @@ -14355,6 +14602,11 @@ components: - $ref: '#/components/schemas/BillingTotalsResponse' nullable: true description: Totals for this subscription item + applied_discount: + allOf: + - $ref: '#/components/schemas/BillingDiscountRedemption' + nullable: true + description: The currently active discount applied to this subscription item, if any required: - object - id