管理周期性 eSIM 流量包
使用周期性订阅按计费周期购买数据套餐。您需要购买 eSIM 服务的权限、组织钱包资金，以及为使用该 eSIM 的人员创建的订阅者。可用性取决于所选的套餐方案和配置文件。
本指南涵盖新购买和在现有 eSIM 上注册订阅。eSIM API 不提供将活跃订阅切换到其他计划的操作。
1. 审查周期性条款
对于新 eSIM，获取结账选项。当 recurrence.available 为 true 时提供自动续订，并使用其 quote 作为已接受的条款。如果不可用，检查 unavailable_reason 并提供支持的购买选项。
对于现有 eSIM，使用 recurring_only=true 列出兼容的套餐方案，然后获取所选方案的周期性条款。注册时会再次检查兼容性，然后才接受购买。
在接受之前，显示周期性价格、发布币种、计费频率和交付模式。报价为税前价格；周期历史记录实际收费总额和税额。calendar_month 按日历月计算；fixed_days 使用指定数量的 24 小时天数。组织钱包支付该服务费用；订阅者没有单独的钱包。
检查套餐是否覆盖已付费的区间（exact_period），还是每次续订购买一个标准套餐（recurring_top_up）。对于周期性充值，激活和到期遵循套餐条款，可能与计费周期边界不同。不要仅因为已安排续订就承诺数据不间断。
2. 分配订阅用户
在控制面板中，从 eSIMs 打开配置文件，打开 More eSIM actions，选择 Assign person，选择联系人，然后确认 Assign person。之后无法更改已分配的人员。
使用 API，通过工作区中联系人的 contact_id 创建订阅者。这需要 Contacts 的 email_marketing:read 和 esim:write。如果该联系人已有订阅者，响应会返回现有的订阅者。
创建关联后将阻止删除联系人，包括在 eSIM 终止之后。订阅者关联目前无法移除、解绑或匿名化。在创建之前，请确定这种数据保留是否符合您的客户流程。
对于现有配置文件，使用 subscriber_id 分配 eSIM。重复相同的分配会返回现有记录；分配不同的人员会返回 409。对于新配置文件，在购买时包含 subscriber_id，以便分配随交付一起完成。
分配不会授予工作区访问权限或读取安装凭据的权限。请使用套餐方案要求和集成指南单独处理身份信息收集。
3. 注册并验证交付
对于已分配的现有 eSIM，在控制面板中打开 Automatic renewal，选择 Set up renewal。选择一个 Package，点击 Check recurring price，查看价格、周期和套餐交付条款。选择 Buy first package and renew 以购买首个计费周期并启用续订。
对于通过 API 购买的新 eSIM，使用所选的 offer_id、工作区 subscriber_id 以及以下已接受的结账条款创建订单：
- 将
offer_revision设置为recurrence.quote.offer_revision。 - 将
recurrence.recurrence_revision设置为recurrence.quote.recurrence_revision。 - 将
recurrence.accepted_price设置为完整的recurrence.quote.price对象。
发送 Idempotency-Key；本次购买中省略 esim_id 和 expected_price。保存订单 ID 及其 recurring_subscription_id。首个计费周期在付款到账后开始。跟踪订单直到完成或失败，如有需要可使用购买恢复步骤。
对于已分配的现有 eSIM，使用 esim_id、offer_id、套餐的 revision（作为 offer_revision）以及续订条款的 revision（作为 recurrence_revision）创建循环订阅。将续订条款的完整 price 作为 accepted_price 发送。Idempotency-Key 为必填项；使用相同请求重复提交可恢复注册。注册会立即购买首个计费周期，不会等待现有套餐用完。
获取订阅并列出其计费周期。分别确认付款和套餐交付。对于新 eSIM，在订单完成后交付安装详情。
4. 监控续期
打开Subscriptions查看已接受的条款、状态和下次续订时间。在 API 中读取 next_renewal_at、stop_reason 和周期历史。已发布价格变更后需要重新接受；未到账的续订付款将停止后续购买。
如果 status 为 needs_attention，检查最近的计费周期和关联订单。交付问题尚未解决时，相关费用可能仍需支付，并且会阻止新的注册。请在购买替代方案前携带这些参考信息联系支持。
5. 停止后续续期
在 eSIM 的 Automatic renewal 部分，选择 Cancel renewal。查看当前已付费周期的结束时间，然后在对话框中确认 Cancel renewal。检查更新后的订阅以确认取消日期。
通过 API，取消订阅，然后重新读取。检查 cancel_at_period_end、cancellation_effective_at 和 next_renewal_at 以确认续订何时结束。已提交的计费周期仍需付款。已交付的套餐保留其自身有效期，已安装的配置文件也会保留。
从手机中移除配置文件不会取消续订。释放 eSIM 会永久停用该 eSIM、没收剩余数据且不予退款。当您需要同时更改连接和续订时，请使用服务操作。
故障排查
充值钱包不会自动重启已停止的订阅。在接受新注册之前，请检查 stop_reason 以及先前服务的最终状态。付费交付失败与其退款是两个独立的结果：请在周期历史中检查 order_status 和 refund_transaction_id。
验证客户旅程
确认客户能够找到已购买的流量额度、套餐到期时间、下次续订日期、取消日期以及支持联系方式。验证首个套餐的交付情况，并在兼容设备上测试移动数据。将后续周期的付款和交付与其计划续订日期分开检查。