Stripe 订阅：每月1日账单设置方法

在 Stripe 订阅管理中，有时需要确保所有用户的账单周期都固定在每月的特定日期，例如每月1日。这对于财务对账、用户体验管理以及提供统一的计费周期至关重要。Stripe 提供了 billing_cycle_anchor 参数来精确控制订阅的计费锚点，结合按月计费的定价计划，即可实现这一目标。

核心概念

要将 Stripe 订阅的账单日期固定在每月1日，需要理解并正确使用以下两个关键组件：

1. 定价计划 (Price Object)： Stripe 的定价计划（Price）定义了产品如何收费，包括计费间隔（例如，每月、每年）和金额。要实现每月1日扣款，首先必须确保订阅所使用的定价计划是按月计费的。

2. billing_cycle_anchor 参数： 这是 Stripe 订阅创建或更新时的一个重要参数。它允许您指定订阅的计费周期应该从哪个时间点开始“锚定”。当设置了 billing_cycle_anchor 后，Stripe 会根据这个锚点和定价计划的计费间隔来计算后续的账单日期。例如，如果按月计费的订阅将 billing_cycle_anchor 设置为某个月的1日，那么后续每个月的1日都将是账单日。这个参数的值必须是一个 Unix 时间戳。

实现步骤

以下是实现 Stripe 订阅每月1日扣款的具体步骤。

1. 确保使用按月计费的定价计划

在创建 Stripe 产品和定价计划时，请务必将计费间隔（recurring.interval）设置为 month。

示例：创建按月计费的 Price

import stripe

# 假设您已经配置了Stripe API密钥

# 创建一个产品 (如果还没有)
product = stripe.Product.create(
    name="高级订阅服务"
)

# 创建一个按月计费的定价计划，价格为10美元
price = stripe.Price.create(
    unit_amount=1000,  # 10.00 美元 (以最小货币单位表示)
    currency="usd",
    recurring={"interval": "month"}, # 设置为按月计费
    product=product.id,
)

print(f"创建的 Price ID: {price.id}")

2. 计算并设置 billing_cycle_anchor 参数

这是最关键的一步。您需要计算出下一个或当前月份1日零点（UTC 时间）的 Unix 时间戳。

计算每月1日零点时间戳的逻辑：

• 获取当前日期。
• 将日期设置为当前月份的1日。
• 将时间设置为00:00:00。
• 将此日期时间对象转换为 Unix 时间戳。

示例：使用 Python 计算并创建订阅

以下代码演示了如何计算当前月份1日零点的 Unix 时间戳，并将其用于创建 Stripe 订阅。

import stripe
import datetime
import pytz # 用于处理时区

# 假设您已经配置了Stripe API密钥
# stripe.api_key = 'YOUR_STRIPE_SECRET_KEY'

# 假设客户 ID 和定价计划 ID 已知
customer_id = 'cus_xxxxxxxxxxxxxx' # 替换为您的客户 ID
price_id = 'price_xxxxxxxxxxxxxx' # 替换为您按月计费的 Price ID

# 1. 获取当前日期
now = datetime.datetime.now(pytz.utc) # 使用 UTC 时间

# 2. 计算当前月份的1日零点
# 如果当前日期是1日，则锚点就是今天1日；
# 如果当前日期不是1日，则锚点是下个月的1日。
# 这样可以确保新订阅从下个月1日开始计费，或从当前月1日开始（如果今天就是1日）。
# 更常见的做法是将其锚定到未来的第一个1日，以避免对当前月份进行不必要的按比例计费。

# 示例：锚定到下一个月的1日（更通用且符合期望）
# 获取下个月的日期
if now.month == 12:
    next_month = now.replace(year=now.year + 1, month=1, day=1, hour=0, minute=0, second=0, microsecond=0)
else:
    next_month = now.replace(month=now.month + 1, day=1, hour=0, minute=0, second=0, microsecond=0)

# 如果当前日期已经是1日，并且您希望它从当前月1日开始，则可以使用以下逻辑：
# current_month_first_day = now.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
# billing_anchor_timestamp = int(current_month_first_day.timestamp())

# 对于从下一个1日开始的场景：
billing_anchor_timestamp = int(next_month.timestamp())

print(f"计算出的 billing_cycle_anchor 时间戳 (下一个月1日): {billing_anchor_timestamp}")
print(f"对应日期: {next_month.strftime('%Y-%m-%d %H:%M:%S UTC')}")

# 3. 创建或更新订阅时设置 billing_cycle_anchor
try:
    subscription = stripe.Subscription.create(
        customer=customer_id,
        items=[
            {"price": price_id},
        ],
        billing_cycle_anchor=billing_anchor_timestamp,
        # 可以根据需要添加其他参数，例如 payment_behavior, collection_method 等
        # payment_behavior='default_incomplete', # 默认行为，或 'allow_incomplete'
        # collection_method='charge_automatically', # 自动扣款
    )
    print(f"成功创建订阅: {subscription.id}")
    print(f"订阅当前周期开始时间 (Unix): {subscription.current_period_start}")
    print(f"订阅当前周期结束时间 (Unix): {subscription.current_period_end}")

except stripe.error.StripeError as e:
    print(f"创建订阅失败: {e}")

更新现有订阅：

如果您需要将现有订阅的计费周期调整到每月1日，也可以通过更新订阅的方式设置 billing_cycle_anchor。

import stripe
import datetime
import pytz

# 假设订阅 ID 已知
subscription_id = 'sub_xxxxxxxxxxxxxx' # 替换为您的订阅 ID

now = datetime.datetime.now(pytz.utc)
if now.month == 12:
    next_month = now.replace(year=now.year + 1, month=1, day=1, hour=0, minute=0, second=0, microsecond=0)
else:
    next_month = now.replace(month=now.month + 1, day=1, hour=0, minute=0, second=0, microsecond=0)

billing_anchor_timestamp = int(next_month.timestamp())

try:
    updated_subscription = stripe.Subscription.modify(
        subscription_id,
        billing_cycle_anchor=billing_anchor_timestamp,
        # 可以选择是否进行按比例计费
        proration_behavior='always_invoice', # 或 'create_prorations', 'none'
    )
    print(f"成功更新订阅: {updated_subscription.id}")
    print(f"更新后订阅当前周期开始时间 (Unix): {updated_subscription.current_period_start}")
    print(f"更新后订阅当前周期结束时间 (Unix): {updated_subscription.current_period_end}")

except stripe.error.StripeError as e:
    print(f"更新订阅失败: {e}")

重要注意事项

• 时区 (pytz): 在计算 Unix 时间戳时，务必使用 UTC 时间。Stripe 内部处理时间戳时通常基于 UTC。使用 pytz.utc 可以确保时间戳的准确性，避免因服务器或本地时区设置不同导致的问题。
• 试用期 (Trial Periods): 如果订阅包含试用期，billing_cycle_anchor 将在试用期结束后生效。例如，如果设置了30天试用期，并且 billing_cycle_anchor 指向下个月的1日，那么订阅将在试用期结束后，于下一个1日开始正式计费。
• 按比例计费 (Proration): 当您设置或更新 billing_cycle_anchor 时，Stripe 可能会根据用户当前已支付的周期和新计费周期之间的差异，自动计算按比例的费用（Proration）。您可以通过 proration_behavior 参数来控制此行为：
  • always_invoice (默认): 立即开具按比例计费的发票。
  • create_prorations: 创建按比例计费的账单项，但不会立即开具发票。
  • none: 不进行按比例计费。 根据您的业务需求选择合适的行为。通常，为了计费的公平性，建议允许按比例计费。
• 现有订阅与新订阅: 对于新订阅，billing_cycle_anchor 会直接决定其初始计费周期。对于现有订阅，修改 billing_cycle_anchor 会调整其下一个和后续的计费周期。
• 幂等性 (Idempotency): 在创建或更新订阅时，使用幂等键（Idempotency Key）可以防止因网络问题导致的重复请求，确保操作只执行一次。

总结

通过正确结合按月计费的 Stripe Price 对象和 billing_cycle_anchor 参数，您可以精确地控制 Stripe 订阅的账单日期，使其固定在每月1日。这不仅有助于简化财务管理，还能为用户提供更清晰、可预测的账单周期。在实施过程中，请务必注意时间戳的准确性、时区处理以及按比例计费的行为，以确保订阅逻辑的健壮性和用户体验的一致性。