Endpoint GET /v2/products/:product_id/subscribers
Retrieve a list of all active subscribers for a specific product. This endpoint returns subscription information including subscriber details, purchase history, and subscription status.
Authentication This endpoint requires the view_sales OAuth scope.
Path Parameters The unique identifier (external ID) or unique permalink of the product
Query Parameters Filter subscribers by email address. The email parameter will be trimmed of whitespace before matching.
Enable pagination for the results. Set to true or 1 to paginate results. Returns up to 100 subscribers per page.
The page key for retrieving the next page of results. This value is returned in the next_page_key field when pagination is enabled and more results are available.
Response Indicates whether the request was successful
Array of subscriber objects The unique external ID of the subscription
The subscriber’s email address
The external ID of the product
The external ID of the user account (if subscriber has a Gumroad account)
The email of the user account (if subscriber has a Gumroad account)
Array of external IDs for all purchases associated with this subscription
ISO 8601 timestamp of when the subscription was created
user_requested_cancellation_at
ISO 8601 timestamp of when the user requested cancellation
The number of times this subscription has been charged (for fixed-length subscriptions)
The billing frequency: monthly, quarterly, biannually, yearly, every_two_years, every_three_years
ISO 8601 timestamp of when the subscription was or will be cancelled
ISO 8601 timestamp of when the subscription ended
ISO 8601 timestamp of when the subscription failed due to payment issues
ISO 8601 timestamp of when the free trial period ends
The license key associated with this subscription (if applicable)
The current status of the subscription: alive, pending_cancellation, pending_failure, cancelled, failed_payment, or fixed_subscription_period_ended
The URL for the next page of results (only present when pagination is enabled and more results are available)
The page key for the next page of results (only present when pagination is enabled and more results are available)
Examples Basic Request curl "https://api.gumroad.com/v2/products/PRODUCT_ID/subscribers" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Filter by Email curl "https://api.gumroad.com/v2/products/PRODUCT_ID/[email protected] " \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Paginated Request curl "https://api.gumroad.com/v2/products/PRODUCT_ID/subscribers?paginated=true" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response Examples Success Response { "success" : true , "subscribers" : [ { "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_123abc" , "purc_456def" , "purc_789ghi" ], "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" }, { "id" : "sub_0987654321fedcba" , "email" : "[email protected] " , "product_id" : "prod_abc123" , "product_name" : "Monthly Membership" , "user_id" : null , "user_email" : null , "purchase_ids" : [ "purc_aaa111" ], "created_at" : "2024-02-20T14:15:00Z" , "user_requested_cancellation_at" : "2024-03-01T09:00:00Z" , "charge_occurrence_count" : null , "recurrence" : "monthly" , "cancelled_at" : "2024-03-20T14:15:00Z" , "ended_at" : null , "failed_at" : null , "free_trial_ends_at" : null , "status" : "pending_cancellation" } ] }
Paginated Response { "success" : true , "subscribers" : [ { "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_123abc" ], "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 , "status" : "alive" } ], "next_page_url" : "/v2/products/prod_abc123/subscribers?page_key=2024-01-15T10:30:00.123456-abc123&paginated=true" , "next_page_key" : "2024-01-15T10:30:00.123456-abc123" }
Error Responses Product Not Found { "success" : false , "message" : "The product was not found." }
Invalid Page Key { "status" : 400 , "error" : "Invalid page_key." }
Insufficient Permissions { "error" : "The access token is invalid" }
HTTP Status: 403 Forbidden
Only active subscriptions are returned by this endpoint. Subscriptions that are test subscriptions, have failed, or have ended are excluded from the results.
When using pagination, the results are limited to 100 subscribers per page. The next_page_key parameter is automatically set when you use the paginated parameter or when you provide a page_key.