Upgrade to API version 2025-11-10

Version 2025-11-10 of Clerk's Frontend and Backend APIs introduces updates to how Clerk Billing formats its responses. These changes improve consistency and clarity across the APIs, making them easier to work with and understand.

To use this new API version, refer to the versioning guide. This guide documents all updates at the API level. Since implementation details may differ between SDKs, it will help you identify which parts of your SDK usage may require additional review in the documentation, and assist consumers using unofficial or custom API clients in managing the upgrade.

The following sections provide a detailed overview of the response type and endpoint changes. In general, these updates fall into one of the following categories:

Updating branding: Clerk Billing was originally developed under the working name "Commerce", which is why /commerce/ appeared in endpoints. This API version standardizes on "Billing" instead of the deprecated "Commerce". Terminology has also been updated for consistency, including renaming "payment sources" to "payment methods".
Clearer handling of missing or empty data: In some cases, a response type has different information depending on the request that prompted the response. Previous API versions handled the absence of this information in inconsistent ways;sometimes using empty values (e.g., "" for strings or 0 for numbers), sometimes null, and sometimes omitting the field entirely. Version 2025-11-10 introduces standardized semantics:
- If the response explicitly indicates that the data doesn't exist, it will be set to null.
- If the response is not making any assertion about the existence of the data, it will not include the key at all.
- If the response is trying to tell you that the data is set to the empty value (e.g., "" for strings, 0 for numbers), it will be set to that value.
Removal of deprecated fields: As our API responses have evolved, several response fields were deprecated but retained for backwards compatibility. This API version removes those deprecated fields.

Backend response type changes

Payers

Name
organization_id
Type
string | null
Description
The organization_id field will now be explicitly null for user payers, instead of omitted.
Name
organization_name
Type
string | null
Description
The organization_name field will now be explicitly null for user payers, instead of omitted. It can still be omitted from certain endpoints that do not provide that data.
Name
user_id
Type
string | null
Description
The user_id field will now be explicity null for organization payers, instead of omitted.
Name
first_name
Type
string | null
Description
The first_name field will now be explicitly null for organization payers, instead of "". It can also be omitted from certain endpoints that do not provide that data.
Name
last_name
Type
string | null
Description
The last_name field will now be explicitly null for organization payers, instead of "". It can also be omitted from certain endpoints that do not provide that data.
Name
email
Type
string | null
Description
The email field will now be explicitly null for organization payers, instead of "". It can also be omitted from certain endpoints that do not provide that data.
Name
image_url
Type
string
Description
The image_url field will now be omitted from endpoints that do not provide that data, instead of returning "".
Name
created_at
Type
number
Description
The created_at field will now be omitted instead of returning 0 when an endpoint does not provide that data.
Name
updated_at
Type
number
Description
The updated_at field will now be omitted instead of returning 0 when an endpoint does not provide that data.

Payment attempts

Name
payment_source_id
Type
string
Description
The payment_source_id field has been removed in favor of the payment_method_id field.
Name
payment_source
Type
BillingPaymentMethodResource
Description
The payment_source field has been removed in favor of the payment_method field.
Name
invoice_id
Type
string
Description
The invoice_id field has been removed in favor of the statement_id field.
Name
gateway_external_id
Type
string | null
Description
The gateway_external_id field can now be explicitly null. Previously, it would be set to "" if unset.
Name
gateway_external_url
Type
string | null
Description
The gateway_external_url field can now be explicitly null. Previously, it was omitted if unset.
Name
paid_at
Type
number | null
Description
The paid_at field can now be explicitly null. Previously, it was unset if the payment attempt had not succeeded yet.
Name
failed_at
Type
number | null
Description
The failed_at field can now be explicitly null. Previously, it was unset if the payment attempt hadn't failed.

Payment methods

The payment sources response type has been renamed to payment methods.

Name
object
Type
string
Description
The object field will now always be "commerce_payment_method".
Name
payment_method
Type
string
Description
The payment_method field has been removed in favor of the payment_type field.
Name
last4
Type
string | null
Description
The last4 field can now be null.
Name
wallet_type
Type
string | null
Description
The wallet_type field can now be null or omitted.
Name
card_type
Type
string | null
Description
The card_type field can now be null.
Name
expiry_year
Type
number | null
Description
The expiry_year field can now be null or omitted.
Name
expiry_month
Type
number | null
Description
The expiry_month field can now be null or omitted.
Name
created_at
Type
number
Description
The created_at field can now be omitted when previously it was set to 0.
Name
updated_at
Type
number
Description
The updated_at field can now be omitted when previously it was set to 0.

Payment method initialize responses

Name
object
Type
string
Description
The object field will now always be "commerce_payment_method_initialize".

Plans

Name
amount
Type
number
Description
The amount field has been removed. Use fee.amount instead.
Name
amount_formatted
Type
string
Description
The amount_formatted field has been removed. Use fee.amount_formatted instead.
Name
annual_monthly_amount
Type
number
Description
The annual_monthly_amount field has been removed. Use annual_monthly_fee.amount instead.
Name
annual_monthly_amount_formatted
Type
string
Description
The annual_monthly_amount_formatted field has been removed. Use annual_monthly_fee.amount_formatted instead.
Name
annual_amount
Type
number
Description
The annual_amount field has been removed. Use annual_fee.amount instead.
Name
annual_amount_formatted
Type
string
Description
The annual_amount_formatted field has been removed. Use annual_fee.amount_formatted instead.
Name
currency
Type
string
Description
The currency field has been removed. Use fee.currency, annual_monthly_fee.currency, or annual_fee.currency instead.
Name
currency_symbol
Type
string
Description
The currency_symbol field has been removed. Use fee.currency_symbol, annual_monthly_fee.currency_symbol, or annual_fee.currency_symbol instead.
Name
payer_type
Type
array of strings
Description
The payer_type field has been removed. Use for_payer_type instead.
Name
description
Type
string | null
Description
The description field can now be null.
Name
avatar_url
Type
string | null
Description
The avatar_url field can now be null.
Name
features
Type
Feature[]
Description
The features field can now be omitted from responses.

Subscription items

Name
plan
Type
BillingPlanResource | null
Description
The plan field can now be null, in preparation for a future change to subscription items that represent an inactive subscription.
Name
plan_id
Type
string | null
Description
The plan_id field can now be null, in preparation for a future change to subscription items that represent an inactive subscription.
Name
lifetime_paid
Type
BillingMoneyAmount
Description
The lifetime_paid field can no longer be null. It will instead be omitted when the endpoint doesn't include that data in the response.
Name
amount
Type
BillingMoneyAmount
Description
The amount field can no longer be null. It will instead be omitted when the endpoint doesn't include that data in the response.
Name
next_invoice
Type
BillingSubscriptionItemResource
Description
The next_invoice field has been removed, in favor of the next_payment field.
Name
next_payment
Type
BillingSubscriptionItemResource
Description
The next_payment field can be omitted when the endpoint doesn't include that data in the response.
Name
payer
Type
BillingPayerResource
Description
The payer field can no longer be null, and will instead be omitted when the endpoint doesn't include that data in the response.
Name
period_start
Type
number
Description
The period_start field can no longer be null.
Name
proration_date
Type
string
Description
The proration_date field can now be omitted when the response does not contain information about proration.
Name
payment_source
Type
BillingPaymentMethodResource
Description
The payment_source field has been removed, in favor of the payment_method field.
Name
payment_source_id
Type
string
Description
The payment_source_id field has been removed, in favor of the payment_method_id field.

Subscription item next payments

Name
amount
Type
BillingMoneyAmount
Description
The amount field can no longer be null.
Name
date
Type
number
Description
The date field can no longer be null.

Backend endpoint changes

The following endpoints have changed their URLs:

Old endpoint	New endpoint
`GET /v1/commerce/plans`	`GET /v1/billing/plans`
`GET /v1/commerce/statements`	`GET /v1/billing/statements`
`GET /v1/commerce/statements/{statementID}`	`GET /v1/billing/statements/{statementID}`
`GET /v1/commerce/statements/{statementID}/payment_attempts`	`GET /v1/billing/statements/{statementID}/payment_attempts`
`GET /v1/commerce/subscription_items`	`GET /v1/billing/subscription_items`
`DELETE /v1/commerce/subscription_items/{subscriptionItemID}`	`DELETE /v1/billing/subscription_items/{subscriptionItemID}`
`POST /v1/commerce/subscription_items/{subscriptionItemID}/extend_free_trial`	`POST /v1/billing/subscription_items/{subscriptionItemID}/extend_free_trial`

Frontend response type changes

Billing settings

Name
enabled
Type
boolean
Description
The enabled field has been removed in favor of the user.enabled and organization.enabled fields.
Name
stripe_publishable_key
Type
string | null
Description
The stripe_publishable_key field can no longer be omitted and will instead be null when unset.
Name
has_paid_user_plans
Type
boolean
Description
The has_paid_user_plans field has been removed in favor of the user.has_paid_plans field.
Name
has_paid_org_plans
Type
boolean
Description
The has_paid_org_plans field has been removed in favor of the organization.has_paid_plans field.

Checkouts

Name
payment_source
Type
BillingPaymentMethodResource
Description
The payment_source field has been removed in favor of the payment_method field.

Invoices

Invoices have been removed in favor of statements.

Payers

Name
organization_id
Type
string | null
Description
The organization_id field will now be explicitly null for user payers, instead of omitted.
Name
organization_name
Type
string | null
Description
The organization_name field will now be explicitly null for user payers, instead of omitted. It can still be omitted from certain endpoints that do not provide that data.
Name
user_id
Type
string | null
Description
The user_id field will now be explicity null for organization payers, instead of omitted.
Name
first_name
Type
string | null
Description
The first_name field will now be explicitly null for organization payers, instead of "". It can also be omitted from certain endpoints that do not provide that data.
Name
last_name
Type
string | null
Description
The last_name field will now be explicitly null for organization payers, instead of "". It can also be omitted from certain endpoints that do not provide that data.
Name
email
Type
string | null
Description
The email field will now be explicitly null for organization payers, instead of "". It can also be omitted from certain endpoints that do not provide that data.
Name
image_url
Type
string
Description
The image_url field will now be omitted from endpoints that do not provide that data, instead of returning "".
Name
created_at
Type
number
Description
The created_at field will now be omitted instead of returning 0 when an endpoint does not provide that data.
Name
updated_at
Type
number
Description
The updated_at field will now be omitted instead of returning 0 when an endpoint does not provide that data.

Payment attempts

Name
payment_source_id
Type
string
Description
The payment_source_id field has been removed in favor of the payment_method_id field.
Name
payment_source
Type
BillingPaymentMethodResource
Description
The payment_source field has been removed in favor of the payment_method field.
Name
invoice_id
Type
string
Description
The invoice_id field has been removed in favor of the statement_id field.
Name
gateway_external_id
Type
string | null
Description
The gateway_external_id field can now be explicitly null. Previously, it would be set to "" if unset.
Name
gateway_external_url
Type
string | null
Description
The gateway_external_url field can now be explicitly null. Previously, it was omitted if unset.
Name
paid_at
Type
number | null
Description
The paid_at field can now be explicitly null. Previously, it was unset if the payment attempt had not succeeded yet.
Name
failed_at
Type
number | null
Description
The failed_at field can now be explicitly null. Previously, it was unset if the payment attempt hadn't failed.

Payment methods

The payment sources response type has been renamed to payment methods.

Name
object
Type
string
Description
The object field will now always be "commerce_payment_method".
Name
payment_method
Type
string
Description
The payment_method field has been removed in favor of the payment_type field.
Name
last4
Type
string | null
Description
The last4 field can now be null.

wallet_type

string | null

The wallet_type field can now be null or omitted.
Name
card_type
Type
string | null
Description
The card_type field can now be null.
Name
expiry_year
Type
number | null
Description
The expiry_year field can now be null or omitted.
Name
expiry_month
Type
number | null
Description
The expiry_month field can now be null or omitted.
Name
created_at
Type
number
Description
The created_at field can now be omitted when previously it was set to 0.
Name
updated_at
Type
number
Description
The updated_at field can now be omitted when previously it was set to 0.

Plans

Name
amount
Type
number
Description
The amount field has been removed. Use fee.amount instead.
Name
amount_formatted
Type
string
Description
The amount_formatted field has been removed. Use fee.amount_formatted instead.
Name
annual_monthly_amount
Type
number
Description
The annual_monthly_amount field has been removed. Use annual_monthly_fee.amount instead.
Name
annual_monthly_amount_formatted
Type
string
Description
The annual_monthly_amount_formatted field has been removed. Use annual_monthly_fee.amount_formatted instead.
Name
annual_amount
Type
number
Description
The annual_amount field has been removed. Use annual_fee.amount instead.
Name
annual_amount_formatted
Type
string
Description
The annual_amount_formatted field has been removed. Use annual_fee.amount_formatted instead.
Name
currency
Type
string
Description
The currency field has been removed. Use fee.currency, annual_monthly_fee.currency, or annual_fee.currency instead.
Name
currency_symbol
Type
string
Description
The currency_symbol field has been removed. Use fee.currency_symbol, annual_monthly_fee.currency_symbol, or annual_fee.currency_symbol instead.
Name
payer_type
Type
string[]
Description
The payer_type field has been removed. Use for_payer_type instead.
Name
description
Type
string | null
Description
The description field can now be null.
Name
avatar_url
Type
string | null
Description
The avatar_url field can now be null.
Name
features
Type
Feature[]
Description
The features field can now be omitted from responses.

Products

Products have been removed.

Subscription next payment objects

Name
time
Type
number
Description
The time field has been removed in favor of the date field.

Subscription items

Name
lifetime_paid
Type
BillingMoneyAmount
Description
The lifetime_paid field can no longer be null. It will instead be omitted when the endpoint doesn't include that data in the response.
Name
amount
Type
BillingMoneyAmount
Description
The amount field can no longer be null. It will instead be omitted when the endpoint doesn't include that data in the response.
Name
next_invoice
Type
BillingSubscriptionItemResource
Description
The next_invoice field has been removed, in favor of the next_payment field.
Name
next_payment
Type
BillingSubscriptionItemResource
Description
The next_payment field can be omitted when the endpoint doesn't include that data in the response.
Name
payer
Type
BillingPayerResource
Description
The payer field can no longer be null, and will instead be omitted when the endpoint doesn't include that data in the response.
Name
period_start
Type
number
Description
The period_start field can no longer be null.
Name
proration_date
Type
string
Description
The proration_date field can now be omitted when the response does not contain information about proration.
Name
payment_source
Type
BillingPaymentMethodResource
Description
The payment_source field has been removed, in favor of the payment_method field.
Name
payment_source_id
Type
string
Description
The payment_source_id field has been removed, in favor of the payment_method_id field.

Subscription item next payments

Name
amount
Type
BillingMoneyAmount
Description
The amount field can no longer be null.
Name
date
Type
number
Description
The date field can no longer be null.

Checkout totals

Name
total_due_after_free_trial
Type
BillingMoneyAmount | null
Description
The total_due_after_free_trial field can no longer be omitted, and will instead be null when it doesn't apply.
Name
credit
Type
BillingMoneyAmount | null
Description
The credit field can no longer be omitted, and will instead be null when it doesn't apply.
Name
past_due
Type
BillingMoneyAmount | null
Description
The past_due field can no longer be omitted, and will instead be null when it doesn't apply.
Name
total_due_now
Type
BillingMoneyAmount | null
Description
The total_due_now field can no longer be omitted, and will instead be null when it doesn't apply.
Name
proration
Type
BillingCheckoutTotals | null
Description
The proration field can no longer be omitted, and will instead be null when it doesn't apply.

Frontend endpoint changes

The following endpoints have changed their URLs:

Old endpoint	New endpoint
`POST /v1/me/commerce/checkouts`	`POST /v1/me/billing/checkouts`
`GET /v1/me/commerce/checkouts/{checkoutID}`	`GET /v1/me/billing/checkouts/{checkoutID}`
`PATCH /v1/me/commerce/checkouts/{checkoutID}/confirm`	`PATCH /v1/me/billing/checkouts/{checkoutID}/confirm`
`POST /v1/organizations/{organizationID}/commerce/checkouts`	`POST /v1/organizations/{organizationID}/billing/checkouts`
`GET /v1/organizations/{organizationID}/commerce/checkouts/{checkoutID}`	`GET /v1/organizations/{organizationID}/billing/checkouts/{checkoutID}`
`PATCH /v1/organizations/{organizationID}/commerce/checkouts/{checkoutID}/confirm`	`PATCH /v1/organizations/{organizationID}/billing/checkouts/{checkoutID}/confirm`
`GET /v1/me/commerce/invoices`	Removed
`GET /v1/organizations/{organizationID}/commerce/invoices`	Removed
`GET /v1/me/commerce/payment_attempts`	`GET /v1/me/billing/payment_attempts`
`GET /v1/me/commerce/payment_attempts/{paymentAttemptID}`	`GET /v1/me/billing/payment_attempts/{paymentAttemptID}`
`GET /v1/organizations/{organizationID}/commerce/payment_attempts`	`GET /v1/organizations/{organizationID}/billing/payment_attempts`
`GET /v1/organizations/{organizationID}/commerce/payment_attempts/{paymentAttemptID}`	`GET /v1/organizations/{organizationID}/billing/payment_attempts/{paymentAttemptID}`
`POST /v1/me/commerce/payment_sources/initialize`	`POST /v1/me/billing/payment_sources/initialize`
`GET /v1/me/commerce/payment_sources`	`GET /v1/me/billing/payment_sources`
`POST /v1/me/commerce/payment_sources`	`POST /v1/me/billing/payment_sources`
`DELETE /v1/me/commerce/payment_sources/{paymentSourceID}`	`DELETE /v1/me/billing/payment_sources/{paymentSourceID}`
`PUT /v1/commerce/payers/default_payment_source`	`PUT /v1/billing/payers/default_payment_source`
`POST /v1/organizations/{organizationID}/commerce/payment_sources/initialize`	`POST /v1/organizations/{organizationID}/billing/payment_sources/initialize`
`GET /v1/organizations/{organizationID}/commerce/payment_sources`	`GET /v1/organizations/{organizationID}/billing/payment_sources`
`POST /v1/organizations/{organizationID}/commerce/payment_sources`	`POST /v1/organizations/{organizationID}/billing/payment_sources`
`DELETE /v1/organizations/{organizationID}/commerce/payment_sources/{paymentSourceID}`	`DELETE /v1/organizations/{organizationID}/billing/payment_sources/{paymentSourceID}`
`PUT /v1/organizations/{organizationID}/commerce/payers/default_payment_source`	`PUT /v1/organizations/{organizationID}/billing/payers/default_payment_source`
`GET /v1/commerce/plans`	`GET /v1/billing/plans`
`GET /v1/commerce/plans/{planIDOrSlug}`	`GET /v1/billing/plans/{planIDOrSlug}`
`GET /v1/commerce/products`	Removed
`GET /v1/me/commerce/statements`	`GET /v1/me/billing/statements`
`GET /v1/me/commerce/statements/{statementID}`	`GET /v1/me/billing/statements/{statementID}`
`GET /v1/organizations/{organizationID}/commerce/statements`	`GET /v1/organizations/{organizationID}/billing/statements`
`GET /v1/organizations/{organizationID}/commerce/statements/{statementID}`	`GET /v1/organizations/{organizationID}/billing/statements/{statementID}`
`GET /v1/me/commerce/subscription`	`GET /v1/me/billing/subscription`
`GET /v1/organizations/{organizationID}/commerce/subscription`	`GET /v1/organizations/{organizationID}/billing/subscription`
`GET /v1/me/commerce/subscription_items`	`GET /v1/me/billing/subscription_items`
`DELETE /v1/me/commerce/subscription_items/{subscriptionItemID}`	`DELETE /v1/me/billing/subscription_items/{subscriptionItemID}`
`GET /v1/organizations/{organizationID}/commerce/subscription_items`	`GET /v1/organizations/{organizationID}/billing/subscription_items`
`DELETE /v1/organizations/{organizationID}/commerce/subscription_items`	`DELETE /v1/organizations/{organizationID}/billing/subscription_items`

Edit on GitHub

Last updated on Nov 11, 2025

Upgrade to API version 2025-11-10

Feedback