Stripe Java SDK v31移除setCoupon()后，如何为已有客户绑定优惠券？

我正在尝试使用Stripe Java SDK为已有Stripe客户绑定优惠券。在Stripe Java SDK v28.0.0版本中，通过CustomerUpdateParams的setCoupon()方法可正常实现该功能，但升级至v31.0.0版本后，setCoupon()方法被移除。我尝试使用putExtraParam()传递优惠券信息，调用无报错但优惠券并未实际绑定到客户（Stripe控制台中无法查看）。

旧版可正常运行代码（v28.0.0） #

CustomerUpdateParams params =
    CustomerUpdateParams.builder()
        .setCoupon("coupon_123")
        .build();

Customer customer = Customer.retrieve(customerId);
customer.update(params);

新版尝试代码（v31.0.0） #

CustomerUpdateParams params =
    CustomerUpdateParams.builder()
        .putExtraParam("coupon", "coupon_123")
        .build();

Customer customer = Customer.retrieve(customerId);
customer.update(params);

问题 #

1. 使用最新版Stripe Java SDK为已有客户绑定优惠券的正确方式是什么？
2. Stripe是否已正式弃用直接为客户绑定优惠券的方式，转而推荐使用促销码或订阅？
3. putExtraParam("coupon",...)是否本应在此场景生效，还是已不再被支持？

我仅使用Stripe Java SDK，不使用原生cURL，希望获得相关指导或官方文档参考。

解答 #

1. 最新版SDK绑定优惠券的正确方式 #

在v31.0.0及以上版本的Stripe Java SDK中，CustomerUpdateParams不再提供直接的setCoupon字符串参数方法，需要通过嵌套的CustomerUpdateParams.Coupon类来构造参数：

CustomerUpdateParams params = CustomerUpdateParams.builder()
    .setCoupon(CustomerUpdateParams.Coupon.builder().setId("coupon_123").build())
    .build();

Customer customer = Customer.retrieve(customerId);
customer.update(params);

如果你的优惠券对应创建了促销码，官方更推荐使用促销码绑定：

CustomerUpdateParams params = CustomerUpdateParams.builder()
    .setPromotionCode("promo_456")
    .build();

Customer customer = Customer.retrieve(customerId);
customer.update(params);

2. 是否弃用直接绑定优惠券的方式 #

Stripe并未完全弃用直接为客户绑定优惠券的方式，但官方更推荐使用促销码（Promotion Code）。促销码是优惠券的封装层，支持更多灵活配置（比如使用次数限制、受众范围等），而直接绑定优惠券的逻辑仍被API支持，只是SDK层面调整了参数的传递结构。

3. putExtraParam("coupon",...)为何不生效 #

putExtraParam用于传递SDK未封装的额外API参数，但当前Stripe API更新客户优惠券的参数结构已从直接传字符串coupon，改为需要嵌套的coupon[id]格式。直接传递字符串不符合API的参数要求，所以调用无报错但实际不生效。SDK的嵌套Coupon类会自动处理正确的参数结构，因此必须使用这种方式传递优惠券ID。

内容的提问来源于stack exchange，提问作者Suraj Dombale