订阅加购服务

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

注意事项

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

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

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

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

• 此功能在韩国 (KR) 不可用。

与 Play 结算库集成

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

启动购买流程

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

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

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

   由 ProductDetailsParams 对象表示的商品会同时指定 ProductDetails（表示订阅商品）和 offerToken（用于选择特定的订阅 base plan 或 offer）。

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 结算库集成到应用中所述。唯一的 区别在于，用户可以通过一次购买交易获得多项 权利。购买包含加购项的订阅会返回多个商品，这些商品可以使用 Google Play 结算库中的 Purchase.getProducts() 检索，然后使用 purchases.subscriptionsv2.get 的 lineItems 列表检索 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 时

实时开发者通知

对于包含多项权利的包含加购项的订阅购买交易，系统不会在实时开发者通知中提供 subscriptionId 字段。不过，您可以使用 Play Developer API 获取购买交易并查看关联的商品权利。

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

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

停用旧价格同类群组

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

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

  示例：

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

  在这种情况下，在用户接受 商品 A 的价格变动之前（直到其处于“已确认”状态），系统不会为此订阅购买交易注册商品 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 实时开发者通知。

付款被拒期间商品过期

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

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

恢复期选择

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

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

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

宽限期

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

账号保留功能

当订阅购买交易处于账号保留状态时，系统会暂停所有订阅商品的使用权限，直到付款恢复为止。

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

示例：

• 用户有一个订阅我的基础方案，每月 1 日续订，然后在 8 月 15 日添加了一个每月 10 美元的加购方案，并提供 7 天的免费试用期。这两件商品均未设置宽限期，并且账号保留期均为 30 天。

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

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

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

• 如果账号在 8 月 25 日（即 9 月 1 日的更广泛续订日期 之前）恢复，用户将在当天重新获得“我的基础方案”和 “加购方案”的使用权限。下一个结算日期将更改为 9 月 4 日。

• 如果账号在 30 天后仍未恢复，订阅将于 9 月 21 日取消，用户将失去“加购方案”的使用权限，并恢复使用 “我的基础方案”的权限，直到 9 月 30 日。

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

财务报告和对账

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

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

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

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