Users
Billing

Retrieve a user's billing subscription

Changed on

Retrieves the billing subscription for the specified user. This includes subscription details, active plans, billing information, and payment status. The subscription contains subscription items which represent the individual plans the user is subscribed to.

get/users/{user_id}/billing/subscription

Request

  • Base URL: https://api.clerk.com/v1
  • URL: https://api.clerk.com/v1/users/{user_id}/billing/subscription
  • Auth: HTTP bearer

Path parameters

user_idstring required

The ID of the user whose subscription to retrieve

Response

A commerce subscription.

object'commerce_subscription' required

String representing the object's type. Objects of the same type share the same value.

idstring required

Unique identifier for the commerce subscription.

instance_idstring required

The ID of the instance this subscription belongs to.

status'active' | 'past_due' | 'canceled' | 'ended' | 'abandoned' | 'incomplete' required

The current status of the subscription.

payer_idstring required

The ID of the payer for this subscription.

created_atinteger required

Unix timestamp (milliseconds) of creation.

updated_atinteger required

Unix timestamp (milliseconds) of last update.

active_atinteger nullable required

Unix timestamp (milliseconds) when the subscription became active.

past_due_atinteger nullable required

Unix timestamp (milliseconds) when the subscription became past due.

eligible_for_free_trialboolean

Whether the payer is eligible for a free trial.

Changes

  • 2025-11-101d47a6af3befRevision changes
    • warning

      added the new payer-credits enum value to the /// response property for the response status

  • 2025-11-10b45c56a4eed9Revision changes
    • info

      added to the / response property allOf list for the response status

    • info

      added to the // response property allOf list for the response status

    • info

      removed from the / response property allOf list for the response status

    • info

      removed from the // response property allOf list for the response status