订阅加购服务

包含加购项的订阅可让您将多个订阅产品捆绑在一起，以便一起购买、结算和管理。您现有的商品清单订阅可以无缝地作为加购项提供，无需任何预先指定或额外配置。您可以启动包含多个现有订阅产品的购买流程，并将这些产品作为加购项销售。

注意事项

使用包含加购项的订阅功能时，请注意以下几点：

• 包含加购项的订阅仅支持自动续订型基础方案。

• 购买交易中的所有商品都必须具有相同的定期结算周期。例如，您不能将按年结算的订阅与按月结算的加购项搭配使用。

• 包含加购项的订阅购买交易最多可以包含 50 件商品。

• 此功能在印度 (IN) 和韩国 (KR) 区域不可用。

与 Play 结算库集成

本部分介绍了如何将包含加购项的订阅功能与 Play 结算库 (PBL) 集成。本部分假定您熟悉 PBL 的初始集成步骤，例如将 PBL 依赖项添加到您的应用、初始化 BillingClient 以及连接到 Google Play。本部分重点介绍了特定于包含加购项的订阅的 PBL 集成方面。

启动购买流程

如需为包含加购项的订阅启动购买流程，请执行以下步骤：

1. 使用 BillingClient.queryProductDetailsAsync 方法提取所有订阅商品。

2. 为每个商品设置 ProductDetailsParams 对象。

   由 ProductDetailsParams 对象表示的商品会同时指定表示订阅商品的 ProductDetails，以及选择特定订阅 base plan 或 offer 的 offerToken。

3. 在 BillingFlowParams.Builder.setProductDetailsParamsList 方法中指定作品详情。 BillingFlowParams 类用于指定购买流程的详细信息。

   以下示例展示了如何为包含多件商品的订阅购买交易启动结算流程：

   Java

      BillingClient billingClient = …;
   
       // ProductDetails obtained from queryProductDetailsAsync().
       ProductDetailsParams productDetails1 = ...;
       ProductDetailsParams productDetails2 = ...;
       ArrayList productDetailsList = new ArrayList<>();
       productDetailsList.add(productDetails1);
       productDetailsList.add(productDetails2);
   
       BillingFlowParams billingFlowParams =
           BillingFlowParams.newBuilder()
              .setProductDetailsParamsList(productDetailsList)
              .build();
       billingClient.launchBillingFlow(billingFlowParams);

适用于购买交易中商品的规则

• 为确保加购项的续订日期最终与基础商品保持一致，Google Play 可能会在任何试用期或初次体验价阶段后插入按比例收取的费用。
• 系统会针对每件商品单独评估优惠资格。

处理购买交易

包含加购项的订阅的处理方式与 将 Google Play 结算库集成到应用中所述的 单个订阅购买交易的处理方式相同。唯一的 区别在于，用户可以通过一次购买交易获得多项 权利。购买包含加购项的订阅 会返回多件商品，这些商品可以使用 Purchase.getProducts()在 Google Play 结算库中检索，然后使用 lineItems 列表在 purchases.subscriptionsv2.get的 Google Play Developer API中检索。

修改包含加购项的订阅

对包含加购项的订阅进行的任何更改都会导致升级或降级。如需了解详情，请参阅 升级或降级订阅。

如需更改或恢复应用中现有的包含加购项的订阅购买交易，您必须使用其他 参数调用 launchBillingFlow API，并确保满足以下条件：

• 始终使用当前订阅购买交易的购买令牌调用 setOldPurchaseToken。
• 如需升级、降级或交叉升级商品，请调用 SubscriptionProductReplacementParams.setReplacementMode，以指定新旧购买商品之间应如何处理方案更改。否则，无需设置 SubscriptionProductReplacementParams。
• 如果基础商品未更改，您仍然可以调用 SubscriptionProductReplacementParams.setSubscriptionReplacementMode 来应用特定的替换行为。如需了解此情况下的适用规则，请参阅重新订阅或在同一订阅中切换方案。
• 新加购项将立即应用，并按比例收取费用，以使下一个续订日期与订阅中的基础商品保持一致。
• 移除的加购项将在当前结算周期结束时失效。
• 启动结算流程时，您需要指定包含加购项的订阅中的所有有效商品（不包括要移除的商品）以及任何新加购项。

以下示例展示了在更改现有包含加购项的订阅购买交易时如何调用 launchBillingFlow API：

BillingClient billingClient = …;

int replacementMode =…;

// ProductDetails obtained from queryProductDetailsAsync().
ProductDetailsParams productDetails1 = ...;
ProductDetailsParams productDetails2 = ...;
ProductDetailsParams productDetails3 = ...;

ArrayList newProductDetailsList = new ArrayList<>();
newProductDetailsList.add(productDetails1);
newProductDetailsList.add(productDetails1);
newProductDetailsList.add(productDetails1);

BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setSubscriptionUpdateParams(
          SubscriptionUpdateParams.newBuilder()
              .setOldPurchaseToken(purchaseTokenOfExistingSubscription)
              // No need to set if change does not affect the base item.
             .setSubscriptionReplacementMode(replacementMode)
             .build())
        .setProductDetailsParamsList(productDetailsList)
        .build();

billingClient.launchBillingFlow(billingFlowParams);

订阅修改场景

下表列出了包含加购项的订阅的各种修改场景以及相应的行为。

使用 SubscriptionProductReplacementParams 时

使用 SubscriptionUpdateParams 时

实时开发者通知

对于包含多项商品使用权的包含加购项的订阅购买交易，RTDN 中未提供 subscriptionId 字段。不过，您可以使用 Play Developer API 获取购买交易并查看关联的商品使用权。

适用于现有订阅者的价格变动

更改包含加购项的订阅购买交易的现有订阅者的订阅价格 与 更改单个订阅的价格类似，如 更改订阅价格中所述。不过，如本部分所述，存在一些限制和功能差异。

停用旧价格同类群组

停用旧同类群组也会影响包含加购项的订阅购买交易。 适用以下规则：

• 所有未完成的“用户选择接受才生效”类型的价格上调都应与新价格具有相同的续订时间。如果包含加购项的订阅购买交易中的某件商品具有用户接受才生效的价格上调，但用户尚未确认，则购买交易中其他商品的任何新的用户接受才生效的价格上调都将被忽略，除非它导致新价格应用的续订时间与处于 OUTSTANDING 状态的现有价格上调相同。用户确认价格上调后，系统会注册任何更新的价格变动。 用户只能一次性接受所有未确认的“用户选择接受才生效”类型的价格上调。

  示例：

  • 假设包含加购项的订阅（商品 A 和 B）每月 7 日续订。
  • 商品 A 的价格正在从 7 美元迁移到 10 美元，预计价格上调将于 7 月 7 日生效。
  • 商品 B 的新价格迁移从 5 美元到 6 美元，于 6 月 2 日开始。由于“用户接受才生效的价格上调”在迁移后 37 天开始，因此商品 B 的最早价格上调时间为 8 月 7 日。

  在这种情况下，在用户接受 商品 A 的价格变动之前（直到其处于 CONFIRMED 状态），商品 B 的价格变动不会注册到此订阅购买交易中， 并且 SubscriptionPurchaseV2 不会返回 商品 B 的价格变动详细信息。用户确认商品 A 的价格变动后，商品 B 的价格变动开始。用户只有在接受商品 A 的用户接受才生效的价格上调后，才会收到商品 B 的用户接受才生效的价格上调。

• Google Play 的电子邮件包含一份列表，其中列出了所有价格上调或下调在当天生效的商品。

取消包含加购项的订阅

用户可以在 Play 订阅中心取消包含加购项的订阅的整个购买交易，而您只能使用 Google Play Developer API 取消包含加购项的订阅的整个购买交易。

如果取消订阅购买交易但未撤消，则购买交易中的任何商品都不会自动续订，但用户将继续有权使用有权使用的商品（包括任何免费试用），直到相应的结算周期结束。

撤消包含加购项的订阅并办理退款

以下是撤消订阅和办理退款的一些准则：

• 使用 Play 管理中心针对特定订单办理金额退款，而无需撤消对订阅的访问权限。

• 调用 orders.refund 以全额退还用户支付的特定订阅款项 ，而无需撤消对订阅的访问权限。

• 调用 purchases.subscriptionsv2.revoke 以立即撤消对所有订阅商品的访问权限 。借助此 API，您可以：

  • 撤消对所有商品的访问权限，并提供按比例退款。

  • 使用按比例退款撤消包含加购项的订阅时，系统将针对每件商品的最新订单办理退款，退款金额将根据距离下一次续订剩余的时间按比例计算。

  • 撤消对所有商品的访问权限，并办理全额退款。

  • 撤消对单个商品的访问权限，并针对 该商品办理全额退款。

撤消包含加购项的订阅中的单个商品

如需撤消包含 加购项的订阅中的单个订阅商品，而无需撤消整个购买交易，请调用 purchases.subscriptionsv2.revoke，并在 RevocationContext 中设置 ItemBasedRefund 字段 。应撤消并退款的商品的 productId 可以在 ItemBasedRefund 字段中设置。

可以为包含一个或多个自动续订型订阅商品的购买交易设置 ItemBasedRefund 字段。

• 如果在撤消 ItemBasedRefund 中指定的商品后，订阅购买交易中仍有有效商品，则只会撤消该商品，并全额退款，而不会中断订阅状态。
• 如果在撤消 ItemBasedRefund 中指定的商品后，订阅购买交易中没有剩余有效商品，则该商品将被撤消并全额退款，并且订阅将被取消。

注意事项

• 使用 ItemBasedRefund 时，一次只能撤消一件商品。如果需要撤消不同的商品，可以多次调用该请求。
• 当订阅购买交易处于任何付款被拒状态，或者 ItemBasedRefund 中指定的商品不属于用户或已过期时，系统会阻止商品撤消。
• 预付费订阅不支持商品撤消。

延迟结算

您可以使用 Purchases.subscriptionsv2:defer方法将包含加购项的订阅的下一个结算日期提前。

延迟包含加购项的订阅时，订阅中的所有商品都会延迟相同的时长。在延迟期内，用户可以继续使用所有商品，但无需付费。所有商品的续订日期都会更新为新日期。

这对于促销活动或客户善意行为非常有用。每次调用该 API，结算最短可延迟一天，最长为一年。您可以在新的结算日期到来之前多次调用该 API，以延长延迟期。

执行此操作时，系统会触发 SUBSCRIPTION_DEFERRED 实时开发者通知。

付款被拒期间商品过期

对于包含加购项的订阅购买交易，某些续订可能只需要延长部分商品的使用权，而不会影响具有未来到期日期的商品。

无论续订涉及哪些商品，如果续订付款被拒，整个订阅购买交易都将进入宽限期和账号保留状态，如下方文档中所述。

恢复期选择

由于宽限期本身仍会授予用户使用权，因此在购买包含加购项的订阅后，如果续订付款被拒，系统会选择所有有效商品中宽限期最短的商品，并将其宽限期和账号冻结期作为此续订的恢复期。

有效商品包括在尝试续订之前在包含加购项的订阅购买交易中有效的商品，但不包括任何新添加的商品（这些商品在恢复后才能获得使用权），也不包括因移除或撤消而不再有效的任何商品。

系统会应用所选宽限期最短的商品的账号保留设置。如果有多个商品的宽限期最短，但账号冻结期不同，则系统会应用最长的账号冻结期。

宽限期

如果订阅续订付款被拒，订阅购买交易将进入宽限期状态。在宽限期内，用户将继续有权使用上一个续订周期中的所有有效商品。宽限期结束后，如果支付方式尚未修复，整个订阅购买交易将进入账号冻结状态。如果在宽限期内有任何其他商品达到续订日期，则在订阅从付款被拒状态恢复后，系统将针对这些商品发起新的扣款尝试。

账号冻结

当订阅购买交易处于账号冻结状态时，对所有订阅商品的访问权限都会暂停，直到付款恢复为止。

如果处于账号冻结状态的订阅已恢复，订阅购买交易将继续按原样存在。如果订阅未恢复，则付款被拒的商品将过期，其他商品的访问权限将在其结算周期的剩余时间内恢复。

示例：

• 用户有一个订阅 My Base Plan ，每月 1 日续订，然后在 8 月 15 日添加了一个每月 10 美元的 Add on plan ，并提供 7 天的免费试用期。这两件商品都没有设置宽限期，并且账号冻结期均为 30 天。

• 8 月 22 日，系统向用户收取了 2.90 美元（10*9/31），按比例计算到 8 月 31 日，但用户的支付方式在此之前已过期，订阅于 8 月 22 日进入付款被拒状态。

当订阅因付款被拒而进入账号冻结状态时，用户无法使用包含加购项的订阅中的任何商品。对于未续订的商品，当订阅因付款已恢复或已取消而退出账号冻结状态时，系统会将剩余时间返还给用户。

在前面的示例中，订阅于 8 月 22 日进入账号冻结状态。

• 如果账号在 8 月 25 日（即 9 月 1 日的更广泛续订日期之前）恢复，用户将在当天重新获得对 My Base Plan 和 Add on plan 的访问权限。下一个结算日期将更改为 9 月 4 日。

• 如果账号在 30 天后仍未恢复，订阅将于 9 月 21 日取消，用户将失去对 Add on plan 的访问权限，并恢复对 My 基础方案 的访问权限，直到 9 月 30 日。

在此示例中，您必须获取包含加购项的订阅中所有商品的更新后的 expiryTime，因为某些商品可能会在宽限期和账号冻结期结束后恢复其使用权。

财务报告和对账

使用收入报告将您的有效订阅与 Play 上的交易进行对账。每个交易订单项都有一个订单 ID。对于代表多件商品的购买交易，收入和估算销售额报告将针对每件商品涉及的每项交易（例如扣款、费用、税费和退款）包含单独的行。

对于 Play 管理中心内的信息中心：

• 控制台的财务报告 部分中显示的收入统计信息按商品细分。

• 订单管理反映了包含加购项的订阅的购买交易，并显示了购买商品的明细列表。在订单管理中，您可以撤消、取消或全额退还用户的购买交易。