Retrieve Subscriber

Endpoint

GET /v2/subscribers/:id

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

string

required

The unique external ID of the subscription

Response

boolean

required

Indicates whether the request was successful

object

required

The subscriber object containing all subscription details

Show Subscriber Object Properties

string

The unique external ID of the subscription

string

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.

string

The external ID of the product

string

The name of the product

string

The external ID of the user account. Will be null if the subscriber doesn’t have a Gumroad account.

string

The email of the user account. Will be null if the subscriber doesn’t have a Gumroad account.

array

Array of external IDs for all purchases associated with this subscription. This includes the original subscription purchase and all recurring charges.

string

ISO 8601 timestamp of when the subscription was created

string

ISO 8601 timestamp of when the user requested cancellation. Will be null if the subscription hasn’t been cancelled.

integer

The total number of times this subscription should be charged. Only applicable for fixed-length subscriptions. Will be null for ongoing subscriptions.

string

The billing frequency. Possible values:

monthly - Charged every month
quarterly - Charged every 3 months
biannually - Charged every 6 months
yearly - Charged every year
every_two_years - Charged every 2 years
every_three_years - Charged every 3 years

string

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.

string

ISO 8601 timestamp of when the subscription ended. This applies to fixed-length subscriptions that have completed all their billing cycles.

string

ISO 8601 timestamp of when the subscription failed due to payment issues. A subscription fails after 5 days of unsuccessful charge attempts.

string

ISO 8601 timestamp of when the free trial period ends. Will be null if there is no free trial.

string

The license key associated with this subscription. Only included if a license key exists for the product.

string

The current status of the subscription. Possible values:

alive - Subscription is active and in good standing
pending_cancellation - Subscription has been cancelled but subscriber still has access until the end of the billing period
pending_failure - The most recent charge failed and the subscription is awaiting retry
cancelled - Subscription has been cancelled and subscriber no longer has access
failed_payment - Subscription failed due to payment issues after multiple retry attempts
fixed_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"

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

import requests

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

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.gumroad.com/v2/subscribers/SUBSCRIPTION_ID');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_ACCESS_TOKEN'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
?>

Response Examples

Active Subscription

{
  "success": true,
  "subscriber": {
    "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_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": "newuser@example.com",
    "product_id": "prod_abc123",
    "product_name": "Premium Membership",
    "user_id": "user_new123",
    "user_email": "newuser@example.com",
    "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": "leaving@example.com",
    "product_id": "prod_abc123",
    "product_name": "Monthly Membership",
    "user_id": "user_leaving456",
    "user_email": "leaving@example.com",
    "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": "student@example.com",
    "product_id": "prod_course456",
    "product_name": "6-Month Course Access",
    "user_id": "user_student999",
    "user_email": "student@example.com",
    "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": "customer@example.com",
    "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.

Getting Started

Products

Sales

Licenses

Subscribers

Other Resources

Retrieve Subscriber

Endpoint

Authentication

Path Parameters

Response

Examples

Basic Request

Response Examples

Active Subscription

Subscription with Free Trial

Pending Cancellation

Fixed-Length Subscription

Non-Gumroad User Subscriber

Error Responses

Subscriber Not Found

Insufficient Permissions

Invalid Access Token

​Endpoint

​Authentication

​Path Parameters

​Response

​Examples

​Basic Request

​Response Examples

​Active Subscription

​Subscription with Free Trial

​Pending Cancellation

​Fixed-Length Subscription

​Non-Gumroad User Subscriber

​Error Responses

​Subscriber Not Found

​Insufficient Permissions

​Invalid Access Token

Endpoint

Authentication

Path Parameters

Response

Examples

Basic Request

Response Examples

Active Subscription

Subscription with Free Trial

Pending Cancellation

Fixed-Length Subscription

Non-Gumroad User Subscriber

Error Responses

Subscriber Not Found

Insufficient Permissions

Invalid Access Token