检索和更新订阅

检索订阅后，您可以使用成功响应中的信息来更改订阅的状态或更新订阅。本页重点介绍可用于检索和更新订阅的不同方式。

检索订阅

如需检索已成功订购或转移的订阅，请使用以下 GET HTTP 请求。

GET https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID

替换以下内容：

  • CUSTOMER_ID：客户的主域名或客户的唯一标识符。
  • SUBSCRIPTION_ID：每个客户独有的订阅标识符。您可以使用检索所有经销商订阅方法来检索此值。

此操作在请求正文中没有参数。

如果响应成功，则会返回 HTTP 200 状态代码和订阅的设置。在以下示例响应中，isInTrial 属性为 false，但没有 trialEndTime 属性，这意味着相应客户从未通过此方案享受过 30 天免费试用。

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "billingMethod": "ONLINE",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "RENEW_CURRENT_USERS_MONTHLY_PAY"
  },
  "purchaseOrderId": "example.com_annual_1",
  "status": "ACTIVE",
  "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
  "skuName": "Google Workspace Business Standard"
}

检索客户的所有订阅

如需检索特定经销商客户已成功订购或转移的所有订阅，请使用以下 GET HTTP 请求并添加授权令牌：

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=CUSTOMER_ID value&pageToken=START_DATE&maxResults=MAX_NUMBER

替换以下内容：

  • CUSTOMER_ID：客户的主域名或客户的唯一标识符。
  • START_DATE：开始日期，格式为 YYYY-MM-DD。
  • MAX_NUMBER：响应页面中返回的结果数上限。

此操作在请求正文中没有参数。

成功的响应会返回 HTTP 200 状态代码，以及客户的订阅和设置列表。订阅列表可能包含在此版本的 Reseller API 中未受管理的商品。

如果您未管理此客户，系统会返回 403 "Forbidden" 错误。

检索客户的所有可转移订阅

如需检索客户的所有可能转移到经销商管理的订阅，请使用以下 GET HTTP 请求，并添加授权令牌。customerId 是必需参数，是检索转销客户的账号时返回的客户唯一标识符。customerAuthToken 是客户提供的转移令牌，专门针对您的转销商 ID。由客户生成后，有效期为 30 天。如需详细了解客户如何生成令牌，请参阅将 Google Workspace 账号转移给转销商。

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=CUSTOMER_ID&customerAuthToken=AUTH_TOKEN&pageToken=START_DATE&maxResults=MAX_NUMBER

替换以下内容：

  • CUSTOMER_ID：客户的主域名或客户的唯一标识符。
  • AUTH_TOKEN：客户提供的与您的转销商 ID 对应的转移令牌。由客户生成后，该令牌的有效期为 30 天。如需详细了解客户如何生成令牌，请参阅将 Google Workspace 账号转移给转销商。 如果此值无效或已过期，API 响应会返回 403 "Forbidden" 错误。
  • START_DATE：开始日期，格式为 YYYY-MM-DD。
  • MAX_NUMBER：响应页面中返回的结果数上限。

此操作在请求正文中没有参数。

如果响应成功，则会返回 HTTP 200 状态代码，以及客户的可转移订阅列表，其中包含转移令牌的到期日期和转移订单中所需的最少席位数。客户可能还持有其他无法转移的订阅。

{
  "kind": "reseller#subscriptions",
  "subscriptions": [
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-6543",
      "subscriptionId": "432",
      "skuId": "1010020028",
      "billingMethod": "ONLINE",
      "creationTime": "1331647980142",
      "plan": {
        "planName": "ANNUAL",
        "isCommitmentPlan": true,
        "commitmentInterval": {
          "startTime": "1331647980142",
          "endTime": "1363183980142"
        }
      },
      "seats": {
        "kind": "subscriptions#seats",
        "numberOfSeats": 10,
        "maximumNumberOfSeats": 500,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "transferInfo": {
        "transferabilityExpirationTime": "1333183980142",
        "minimumTransferableSeats": "20"
      },
      "purchaseOrderId": "PO_890",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-6543",
      "subscriptionId": "140",
      "skuId": "1010020028",
      "creationTime": "1329389322728",
      "plan": {
        "planName": "FLEXIBLE",
        "isCommitmentPlan": false
      },
      "seats": {
        "kind": "subscriptions#seats",
        "maximumNumberOfSeats": 50
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false,
        "trialEndTime": "1331877480016"
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "transferInfo": {
        "transferabilityExpirationTime": "1333183780159",
        "minimumTransferableSeats": "10"
      },
      "purchaseOrderId": "",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
  ],
  "nextPageToken": "token"
}

如果您打算使用批量操作转移这些订阅，请转移所有订阅。逐个转移每个订阅会导致错误。此外，批量操作仅转移状态为 ACTIVE 的订阅。如需了解详情，请参阅转移订阅。

检索所有转销商订阅

如需检索经销商成功订购或转移的所有订阅，请使用以下 GET HTTP 请求并包含授权令牌。

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=PREFIX &pageToken=TOKEN&maxResults=MAX_NUMBER

替换以下内容：

  • PREFIX：您要查找的订阅所对应的客户名称的开头部分。
  • TOKEN：用于标识服务器应返回的特定结果页面的令牌。
  • MAX_NUMBER：响应页面中返回的结果数上限。

此操作可以使用 OAuth 只读访问权限范围。customerNamePrefix、pageToken 和 maxResults 是可选的查询字符串。

以下示例检索了经销商的所有订阅，这些订阅属于名称以“exam”开头的客户：

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=exam

{
  "kind": "reseller#subscriptions",
  "subscriptions": [
    {
      "kind": "subscriptions#subscription",
      "customerId": "C0123456",
      "subscriptionId": "123",
      "skuId": "1010020028",
      "creationTime": "1331647980142",
      "billingMethod": "ONLINE",
      "plan": {
        "planName": "ANNUAL",
        "isCommitmentPlan": true,
        "commitmentInterval": {
          "startTime": "1331647980142",
          "endTime": "1363183980142"
        }
      },
      "seats": {
        "kind": "subscriptions#seats",
        "numberOfSeats": 10,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "purchaseOrderId": "PO_135",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-5678",
      "subscriptionId": "1404686",
      "skuId": "1010020028",
      "billingMethod": "ONLINE",
      "creationTime": "1329389322728",
      "plan": {
        "planName": "FLEXIBLE",
        "isCommitmentPlan": false
      },
      "seats": {
        "kind": "subscriptions#seats",
        "maximumNumberOfSeats": 50,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false,
        "trialEndTime": "1331877480016"
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "AUTO_RENEW"
      },
      "purchaseOrderId": "",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
  ],
  "nextPageToken": "token"
}

更新订阅方案

更新 Google Workspace 方案的方式因方案而异。在更新方案之前，请考虑以下事项：

  • 当您创建订阅时，如果客户符合条件，则订阅方案可以是 30 天试用方案。弹性方案和包年合约付款方案均可提供 30 天免费试用。在试用期内，您可以根据需要随时将订阅的付款方案更改为弹性方案或包年套餐。不过，在试用期结束后，当方案变为有效方案时，更新方案的规则与其他订阅的有效方案相同。如需立即将试用订阅转换为有效方案，请将 30 天免费试用订阅转换为付费服务。 如需详细了解 30 天试用期和客户资格规则，请参阅管理帮助中心。

  • 您可以将灵活方案更新为年度承诺方案。

  • 您无法更新年度承诺方案。

  • 并非所有方案都适用于所有产品。如需详细了解这些方案所使用的产品，请参阅产品和 SKU。

如需将 30 天试用方案或灵活方案订阅更新为年限合约方案，请使用以下 POST HTTP 请求：

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changePlan

替换以下内容：

  • CUSTOMER_ID：客户的主域名或客户的唯一标识符。
  • SUBSCRIPTION_ID：每个客户独有的订阅标识符。您可以使用检索所有经销商订阅方法来检索此值。

以下示例使用值为 123 的 subscriptionId 更新订阅。customerId 为 C0123456。

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/changePlan

请求正文具有以下内容：

{
  "kind": "reseller#changePlanRequest",
  "planName": "ANNUAL_MONTHLY_PAY",
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10
  },
  "purchaseOrderId": "123_March2012"
}

成功的响应会返回 HTTP 201 状态代码，并返回更新后的订阅方案设置：

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "purchaseOrderId": "123_March2012",
  "status": "ACTIVE",
  "skuName": "Google Workspace Business Standard"
}

更新订阅的席位数

更新包年承诺方案订阅所使用的订阅属性与更新 Google Workspace 弹性方案订阅所使用的订阅属性不同。

更新包年方案订阅的席位数

如需更新年付方案订阅的用户许可设置，请使用以下 POST HTTP 请求：

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changeSeats

替换以下内容：

  • CUSTOMER_ID：客户的主域名或客户的唯一标识符。
  • SUBSCRIPTION_ID：每个客户独有的订阅标识符。您可以使用检索所有经销商订阅方法来检索此值。

以下示例使用 123 subscriptionId 更新订阅。customerId 为 C0123456。请求正文因方案类型而异：

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/changeSeats

Google Workspace 年度合约方案的订阅使用此请求正文来更新用户许可数量。numberOfSeats 值是总数。例如，如果您之前有 10 个用户许可，并且有客户订购了 5 个新许可，则请求正文中 numberOfSeats 的总数为 15，如以下示例所示：

{
    "kind": "subscriptions#seats",
    "numberOfSeats": 15
}

更新弹性方案订阅的席位数

Google Workspace 弹性方案的订阅使用请求正文来更新用户许可。maximumNumberOfSeats 值是现有许可和新许可的总和。这是相应账号可配置的用户许可数量上限。

{
  "kind": "subscriptions#seats",
  "maximumNumberOfSeats": 15
}

成功的响应会返回 HTTP 201 状态代码和更新后的订阅许可设置：

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "FLEXIBLE",
    "isCommitmentPlan": false
  },
  "seats": {
    "kind": "subscriptions#seats",
    "maximumNumberOfSeats": 15,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "skuName": "Google Workspace Business Standard"
}

更新订阅的续订设置

如需更新年合约订阅的续订设置，请使用以下 POST HTTP 请求：

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changeRenewalSettings

替换以下内容：

  • CUSTOMER_ID：客户的主域名或客户的唯一标识符。
  • SUBSCRIPTION_ID：每个客户独有的订阅标识符。您可以使用检索所有经销商订阅方法来检索此值。

以下是一个请求正文示例：

{
  "kind": "subscriptions#renewalSettings",
  "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
}

renewalType 属性的值可以是以下任一值：

  • AUTO_RENEW_YEARLY_PAY：在包年合约方案的间隔结束时，自动将订阅的方案续订为具有相同 numberOfSeats 的 ANNUAL_YEARLY_PAY。
  • AUTO_RENEW_MONTHLY_PAY：在包年承诺方案的间隔结束时，自动将订阅的方案续订为具有相同 numberOfSeats 的 ANNUAL_MONTHLY_PAY。
  • RENEW_CURRENT_USERS_YEARLY_PAY：在包年合约方案的间隔结束时，将订阅方案续订为 ANNUAL_YEARLY_PAY，但使用当前有效用户许可的总数。这是有效包年套餐（按年付款）的默认设置。
  • RENEW_CURRENT_USERS_MONTHLY_PAY：在包年合约方案的间隔结束时，将订阅方案续订为 ANNUAL_MONTHLY_PAY，但使用当前有效用户许可的总数。这是有效包年套餐（按月付款）的默认设置。
  • RENEW_ON_PROPOSED_OFFER：在当前承诺方案的间隔结束时，按照最新的续订建议进行续订，续订的许可数量为当前有效用户许可数量或建议的优惠承诺（以较高者为准）。
  • SWITCH_TO_PAY_AS_YOU_GO：在年度承诺方案的间隔结束时，将年度承诺方案更改为灵活方案。
  • CANCEL：在包年套餐间隔结束时，订阅会被暂停。如需了解如何解除中止状态，请参阅管理员帮助中心。

成功的响应会返回 HTTP 201 状态代码和更新后的订阅续订设置：

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 15,
    "licensedNumberOfSeats": 15
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "skuName": "Google Workspace Business Standard"
}

从免费试用订阅开始使用付费服务

如需立即将 30 天的免费试用订阅转换为付费服务订阅，请使用以下 POST HTTP 请求（前提是已为试用订阅设置付款方案）。

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/startPaidService

替换以下内容：

  • CUSTOMER_ID：客户的主域名或客户的唯一标识符。
  • SUBSCRIPTION_ID：每个客户独有的订阅标识符。您可以使用检索所有经销商订阅方法来检索此值。

以下示例的 customerId 为 C0123456，subscriptionId 值为 123：

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/startPaidService

此操作在请求正文中没有参数。

成功的响应会返回 HTTP 201 状态代码和更新后的订阅设置：

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 15,
    "licensedNumberOfSeats": 15
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "skuName": "Google Workspace Business Standard"
}

升级或降级订阅

您无法在包年套餐的有效期内降级，也无法通过续订设置来安排降级。我们建议您将续订设置设为切换到 FLEXIBLE，然后在续订时间过后降级。

如需升级或降级订阅，请创建新订阅，并使用您要升级或降级到的 skuId。

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions

替换以下内容：

  • CUSTOMER_ID：客户的主域名或客户的唯一标识符。

此调用会终止之前的订阅并创建新的订阅。

如需详细了解升级和降级，请访问“产品和 SKU”页面。