如何通过 REST API 获取 Google Workspace 有效订阅列表？

2026-10-24数据阿明

结论

普通 Google Workspace 超级管理员目前无法通过公开的 REST API，直接获取与 Admin console 中 Billing → Subscriptions 页面完全一致的订阅列表。

如果订阅由 Google Workspace 经销商管理，经销商可以通过 Google Workspace Reseller API 的 subscriptions.list 方法查询自己管理的客户订阅。这个接口并不适用于所有普通客户账号，也不保证包含 Google 直销或其他渠道管理的订阅。

经销商账号的查询方式

请求端点：

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions

常用查询参数：

customerId：客户的主域名或 Google 分配的客户 ID。
maxResults：每页返回的记录数。
pageToken：用于获取下一页数据。

OAuth 作用域：

https://www.googleapis.com/auth/apps.order

示例请求：

curl \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=example.com"

返回结果的 subscriptions 数组中包含订阅的 SKU、方案、席位和状态等信息。如果只需要有效订阅，可以在应用中按 status 字段筛选：

const response = await fetch(
  "https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=example.com",
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  }
);

if (!response.ok) {
  throw new Error(`Reseller API failed: ${response.status}`);
}

const data = await response.json();

const activeSubscriptions = (data.subscriptions ?? []).filter(
  subscription => subscription.status === "ACTIVE"
);

console.log(
  activeSubscriptions.map(subscription => ({
    subscriptionId: subscription.subscriptionId,
    skuId: subscription.skuId,
    customerId: subscription.customerId,
    status: subscription.status,
  }))
);

生产环境还需要处理分页：

async function listSubscriptions(customerId, accessToken) {
  const subscriptions = [];
  let pageToken;

  do {
    const url = new URL(
      "https://reseller.googleapis.com/apps/reseller/v1/subscriptions"
    );

    url.searchParams.set("customerId", customerId);
    url.searchParams.set("maxResults", "100");

    if (pageToken) {
      url.searchParams.set("pageToken", pageToken);
    }

    const response = await fetch(url, {
      headers: {
        Authorization: `Bearer ${accessToken}`,
      },
    });

    if (!response.ok) {
      throw new Error(
        `Reseller API failed: ${response.status} ${await response.text()}`
      );
    }

    const data = await response.json();
    subscriptions.push(...(data.subscriptions ?? []));
    pageToken = data.nextPageToken;
  } while (pageToken);

  return subscriptions.filter(subscription => subscription.status === "ACTIVE");
}

普通管理员可采用的替代方案

如果组织直接向 Google 购买订阅，或者当前凭据不属于经销商账号，就无法依靠 Reseller API 复现 Billing 页面。此时可以采用以下方式：

在 Admin console 的 Billing → Subscriptions 页面查看订阅。
通过 Admin SDK 的 Licensing API 查询许可证分配情况。
通过 Reports API 获取部分许可证或账号统计数据。
如需自动对账，可向订阅经销商索取 API 或报表接口。

Licensing API 和 Reports API 提供的是许可证分配、使用情况或统计信息，不是计费订阅资源，因而不能替代 Billing → Subscriptions 页面。

注意事项

subscriptions.list 只返回调用方有权管理的订阅，不能代表该客户通过所有销售渠道购买的完整订阅。
拥有超级管理员权限，并不代表同时拥有 Reseller API 权限。
服务账号必须正确配置 OAuth 授权。仅启用域范围委派，不能让普通客户获得经销商能力。
不要根据许可证分配数量反推订阅列表。试用、暂停、按使用量计费和不同购买渠道，都可能使推算结果与 Admin console 不一致。
订阅状态和返回字段应以接口的实际响应及当前官方 API 文档为准。筛选数据时，不要假定每条记录一定包含 status。