Endpoint Retrieve detailed information about a specific subscriber using their subscription ID. This endpoint returns comprehensive subscription details including subscriber information, purchase history, billing status, and more.
Authentication This endpoint requires the view_sales OAuth scope.
Path Parameters The unique external ID of the subscription
Response Indicates whether the request was successful
The subscriber object containing all subscription details Show Subscriber Object Properties
The unique external ID of the subscription
The subscriber’s email address. This can be from the user account, or from the original purchase if the subscriber doesn’t have a Gumroad account.
The external ID of the product
The external ID of the user account. Will be null if the subscriber doesn’t have a Gumroad account.
The email of the user account. Will be null if the subscriber doesn’t have a Gumroad account.
Array of external IDs for all purchases associated with this subscription. This includes the original subscription purchase and all recurring charges.
ISO 8601 timestamp of when the subscription was created
user_requested_cancellation_at
ISO 8601 timestamp of when the user requested cancellation. Will be null if the subscription hasn’t been cancelled.
The total number of times this subscription should be charged. Only applicable for fixed-length subscriptions. Will be null for ongoing subscriptions.
The billing frequency. Possible values:
monthly - Charged every monthquarterly - Charged every 3 monthsbiannually - Charged every 6 monthsyearly - Charged every yearevery_two_years - Charged every 2 yearsevery_three_years - Charged every 3 years ISO 8601 timestamp of when the subscription was or will be cancelled. If this date is in the future, the subscription is in a “pending cancellation” state and the subscriber still has access.
ISO 8601 timestamp of when the subscription ended. This applies to fixed-length subscriptions that have completed all their billing cycles.
ISO 8601 timestamp of when the subscription failed due to payment issues. A subscription fails after 5 days of unsuccessful charge attempts.
ISO 8601 timestamp of when the free trial period ends. Will be null if there is no free trial.
The license key associated with this subscription. Only included if a license key exists for the product.
The current status of the subscription. Possible values:
alive - Subscription is active and in good standingpending_cancellation - Subscription has been cancelled but subscriber still has access until the end of the billing periodpending_failure - The most recent charge failed and the subscription is awaiting retrycancelled - Subscription has been cancelled and subscriber no longer has accessfailed_payment - Subscription failed due to payment issues after multiple retry attemptsfixed_subscription_period_ended - Fixed-length subscription completed all billing cycles Examples Basic Request curl "https://api.gumroad.com/v2/subscribers/SUBSCRIPTION_ID" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response Examples Active Subscription { "success" : true , "subscriber" : { "id" : "sub_1234567890abcdef" , "email" : "[email protected] " , "product_id" : "prod_abc123" , "product_name" : "Monthly Membership" , "user_id" : "user_xyz789" , "user_email" : "[email protected] " , "purchase_ids" : [ "purc_original123" , "purc_renewal456" , "purc_renewal789" ], "created_at" : "2024-01-15T10:30:00Z" , "user_requested_cancellation_at" : null , "charge_occurrence_count" : null , "recurrence" : "monthly" , "cancelled_at" : null , "ended_at" : null , "failed_at" : null , "free_trial_ends_at" : null , "license_key" : "ABCD-1234-EFGH-5678" , "status" : "alive" } }
Subscription with Free Trial { "success" : true , "subscriber" : { "id" : "sub_trial123456789" , "email" : "[email protected] " , "product_id" : "prod_abc123" , "product_name" : "Premium Membership" , "user_id" : "user_new123" , "user_email" : "[email protected] " , "purchase_ids" : [ "purc_trial001" ], "created_at" : "2024-03-01T08:00:00Z" , "user_requested_cancellation_at" : null , "charge_occurrence_count" : null , "recurrence" : "monthly" , "cancelled_at" : null , "ended_at" : null , "failed_at" : null , "free_trial_ends_at" : "2024-03-08T08:00:00Z" , "license_key" : "TRIAL-9876-WXYZ-4321" , "status" : "alive" } }
Pending Cancellation { "success" : true , "subscriber" : { "id" : "sub_cancelling123" , "email" : "[email protected] " , "product_id" : "prod_abc123" , "product_name" : "Monthly Membership" , "user_id" : "user_leaving456" , "user_email" : "[email protected] " , "purchase_ids" : [ "purc_123abc" , "purc_456def" ], "created_at" : "2024-02-01T12:00:00Z" , "user_requested_cancellation_at" : "2024-03-05T10:30:00Z" , "charge_occurrence_count" : null , "recurrence" : "monthly" , "cancelled_at" : "2024-04-01T12:00:00Z" , "ended_at" : null , "failed_at" : null , "free_trial_ends_at" : null , "status" : "pending_cancellation" } }
Fixed-Length Subscription { "success" : true , "subscriber" : { "id" : "sub_fixed789" , "email" : "[email protected] " , "product_id" : "prod_course456" , "product_name" : "6-Month Course Access" , "user_id" : "user_student999" , "user_email" : "[email protected] " , "purchase_ids" : [ "purc_m1_abc" , "purc_m2_def" , "purc_m3_ghi" ], "created_at" : "2024-01-01T00:00:00Z" , "user_requested_cancellation_at" : null , "charge_occurrence_count" : 6 , "recurrence" : "monthly" , "cancelled_at" : null , "ended_at" : null , "failed_at" : null , "free_trial_ends_at" : null , "status" : "alive" } }
Non-Gumroad User Subscriber { "success" : true , "subscriber" : { "id" : "sub_nogumroad123" , "email" : "[email protected] " , "product_id" : "prod_abc123" , "product_name" : "Monthly Newsletter" , "user_id" : null , "user_email" : null , "purchase_ids" : [ "purc_ext001" , "purc_ext002" ], "created_at" : "2024-02-10T15:45:00Z" , "user_requested_cancellation_at" : null , "charge_occurrence_count" : null , "recurrence" : "monthly" , "cancelled_at" : null , "ended_at" : null , "failed_at" : null , "free_trial_ends_at" : null , "status" : "alive" } }
Error Responses Subscriber Not Found { "success" : false , "message" : "The subscriber was not found." }
This error occurs when:
The subscription ID doesn’t exist
The subscription doesn’t belong to a product owned by the authenticated user
The subscription ID is invalid
Insufficient Permissions { "error" : "The access token is invalid" }
HTTP Status: 403 Forbidden
This error occurs when the access token doesn’t have the view_sales scope.
Invalid Access Token { "error" : "The access token is invalid" }
HTTP Status: 401 Unauthorized
This endpoint only returns subscriptions that belong to products owned by the authenticated user. You cannot retrieve subscription information for products you don’t own.
The purchase_ids array includes all purchases associated with the subscription, ordered chronologically. The first ID is the original subscription purchase, and subsequent IDs are recurring charges.