List Subscribers

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

string

required

The unique identifier (external ID) or unique permalink of the product

Query Parameters

string

Filter subscribers by email address. The email parameter will be trimmed of whitespace before matching.

boolean

Enable pagination for the results. Set to true or 1 to paginate results. Returns up to 100 subscribers per page.

string

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

boolean

required

Indicates whether the request was successful

array

required

Array of subscriber objects

Show Subscriber Object

string

The unique external ID of the subscription

string

The subscriber’s email address

string

The external ID of the product

string

The name of the product

string

The external ID of the user account (if subscriber has a Gumroad account)

string

The email of the user account (if subscriber has a Gumroad account)

array

Array of external IDs for all purchases associated with this subscription

string

ISO 8601 timestamp of when the subscription was created

string

ISO 8601 timestamp of when the user requested cancellation

integer

The number of times this subscription has been charged (for fixed-length subscriptions)

string

The billing frequency: monthly, quarterly, biannually, yearly, every_two_years, every_three_years

string

ISO 8601 timestamp of when the subscription was or will be cancelled

string

ISO 8601 timestamp of when the subscription ended

string

ISO 8601 timestamp of when the subscription failed due to payment issues

string

ISO 8601 timestamp of when the free trial period ends

string

The license key associated with this subscription (if applicable)

string

The current status of the subscription: alive, pending_cancellation, pending_failure, cancelled, failed_payment, or fixed_subscription_period_ended

string

The URL for the next page of results (only present when pagination is enabled and more results are available)

string

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"

const response = await fetch(
  'https://api.gumroad.com/v2/products/PRODUCT_ID/subscribers',
  {
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    }
  }
);
const data = await response.json();

import requests

response = requests.get(
    'https://api.gumroad.com/v2/products/PRODUCT_ID/subscribers',
    headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
)
data = response.json()

Filter by Email

curl "https://api.gumroad.com/v2/products/PRODUCT_ID/subscribers?email=user@example.com" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const response = await fetch(
  'https://api.gumroad.com/v2/products/PRODUCT_ID/subscribers?email=user@example.com',
  {
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    }
  }
);
const data = await response.json();

import requests

response = requests.get(
    'https://api.gumroad.com/v2/products/PRODUCT_ID/subscribers',
    params={'email': 'user@example.com'},
    headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
)
data = response.json()

Paginated Request

curl "https://api.gumroad.com/v2/products/PRODUCT_ID/subscribers?paginated=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const response = await fetch(
  'https://api.gumroad.com/v2/products/PRODUCT_ID/subscribers?paginated=true',
  {
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    }
  }
);
const data = await response.json();

// Get next page if available
if (data.next_page_key) {
  const nextResponse = await fetch(
    `https://api.gumroad.com/v2/products/PRODUCT_ID/subscribers?page_key=${data.next_page_key}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
      }
    }
  );
  const nextData = await nextResponse.json();
}

import requests

response = requests.get(
    'https://api.gumroad.com/v2/products/PRODUCT_ID/subscribers',
    params={'paginated': 'true'},
    headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
)
data = response.json()

# Get next page if available
if 'next_page_key' in data:
    next_response = requests.get(
        'https://api.gumroad.com/v2/products/PRODUCT_ID/subscribers',
        params={'page_key': data['next_page_key']},
        headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
    )
    next_data = next_response.json()

Response Examples

Success Response

{
  "success": true,
  "subscribers": [
    {
      "id": "sub_1234567890abcdef",
      "email": "subscriber@example.com",
      "product_id": "prod_abc123",
      "product_name": "Monthly Membership",
      "user_id": "user_xyz789",
      "user_email": "subscriber@example.com",
      "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": "another@example.com",
      "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": "subscriber@example.com",
      "product_id": "prod_abc123",
      "product_name": "Monthly Membership",
      "user_id": "user_xyz789",
      "user_email": "subscriber@example.com",
      "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.

Getting Started

Products

Sales

Licenses

Subscribers

Other Resources

List Subscribers

Endpoint

Authentication

Path Parameters

Query Parameters

Response

Examples

Basic Request

Filter by Email

Paginated Request

Response Examples

Success Response

Paginated Response

Error Responses

Product Not Found

Invalid Page Key

Insufficient Permissions

​Endpoint

​Authentication

​Path Parameters

​Query Parameters

​Response

​Examples

​Basic Request

​Filter by Email

​Paginated Request

​Response Examples

​Success Response

​Paginated Response

​Error Responses

​Product Not Found

​Invalid Page Key

​Insufficient Permissions

Endpoint

Authentication

Path Parameters

Query Parameters

Response

Examples

Basic Request

Filter by Email

Paginated Request

Response Examples

Success Response

Paginated Response

Error Responses

Product Not Found

Invalid Page Key

Insufficient Permissions