Stripe Invoice 的 draft、open、paid、uncollectible、void、auto_advance、collection_method 和 due_date 有什么区别？
Stripe Invoice 不会从“创建”一步跳到“收款完成”。它先以 draft 汇总客户、Invoice Items、Subscription 周期费用、折扣和税费；finalize 后通常进入 open，此时账单金额和编号被确定并等待付款；成功收齐后为 paid；确认无法收回时可以标记 uncollectible；账单作废则为 void。
本文目录（23 节）
快速对照
| 字段或状态 | 类型 | 核心含义 | 是否还能常规修改金额 | 是否表示收到款项 |
|---|---|---|---|---|
draft | status | 草稿，尚未最终确定 | 通常可以 | 否 |
open | status | 已 finalized，仍待收款 | 核心金额字段受限 | 否 |
paid | status | 发票已支付或按 Stripe 规则视为支付 | 不应直接改账单 | 是/被标记为已付 |
uncollectible | status | 已确认坏账、无法收回 | 不作为普通草稿修改 | 否 |
void | status | 发票作废 | 不可作为有效应收继续使用 | 否 |
auto_advance | 控制字段 | 是否由 Stripe 自动 finalized、收款和推进 | 不决定当前 status | 否 |
collection_ | 收款策略 | charge_ 或 send_invoice | 不决定是否 finalized | 否 |
due_date | 时间字段 | 客户应付款日期 | 主要用于 send_invoice | 否 |
Invoice 生命周期与付款生命周期不同
Invoice status 描述账单文档本身的会计/收款阶段。底层 PaymentIntent、Charge 或付款方式还各有自己的状态。open Invoice 可以正在等待客户操作、等待异步付款方式确认、进入重试，也可能尚未创建成功扣款。
不要把 invoice. 直接翻译为 PaymentIntent requires_，也不要看到 Charge succeeded 就忽略 Invoice 是否真正变为 paid。税费调整、余额抵扣、最小可扣金额和带外付款都可能让对象关系不是简单一对一。
业务授权应以需要的对象和事件为准：开通订阅服务通常关注 Invoice/
draft：可编辑的账单草稿
创建 Invoice 后通常先进入 draft。在草稿阶段可添加或删除 Invoice Items、调整部分客户与账单字段、折扣、税务设置和描述，并检查金额是否符合预期。Subscription 生成的周期账单也会经历草稿阶段。
draft 不表示已向客户正式提出付款要求，也没有完成收款。应用若在 invoice.created 后立即发货，会把仍可能变化的草稿当成已付款凭证。
草稿也不能无限搁置而无人管理。若 auto_advance=true，Stripe 会根据流程自动 finalized；若设为 false，则需要应用或运营人员显式推进。监控应发现超过预期时间仍为 draft 的发票。
finalize：从可编辑草稿变成正式发票
Finalization 是状态转换动作，不是独立 status。调用 finalize 或由 Stripe 自动推进后，发票从 draft 通常进入 open，并获得正式编号、Hosted Invoice Page 与 PDF 等正式账单能力。关键金额和行项目不再像草稿那样自由修改。
Finalization 之前应完成税务、客户地址、折扣、货币、行项目和自定义字段检查。错误账单一旦 finalized，修正通常要使用 credit note、void 或新发票等受审计流程，而不是直接重写历史金额。
金额为零、客户余额足额覆盖或某些特殊配置下，finalization 后可能直接变为 paid。不要把“finalize API 返回成功”硬编码为“下一状态一定 open”，应读取返回对象的真实 status。
open：正式应收但尚未结清
open 表示发票已经 finalized，仍需完成付款。对于自动扣款，Stripe 会尝试使用客户设置的付款方式；对于发送发票，客户通过 Hosted Invoice Page 或支持的流程在到期日前付款。
Open 不是失败状态。新发票刚 finalize、银行转账尚未匹配、3D Secure 等客户操作未完成或尚未到 due date，都可能合理停留在 open。
判断异常要结合 attempt_count、attempted、next_、PaymentIntent、last finalization error 和 webhook。单看创建时间会把合法净账期发票误报为逾期。
paid：发票结清
paid 表示 Stripe 将发票视为已支付。常见原因是自动或客户发起的付款成功，也可能通过 API 标记为 paid，包含 out-of-band payment 等场景。业务需要区分“Stripe 在线收款成功”和“运营人员声明线下已收款”时，应检查相关字段与审计记录。
Paid 是发货、开通服务和收入确认的重要信号，但 webhook 可能重复、延迟或乱序。处理 invoice.paid 应实现幂等：以 Invoice ID 作为业务去重键，读取最新对象状态，再执行一次性动作。
付款后退款或发生 dispute，不一定把 Invoice status 自动改回 open。退款、争议、Credit Note 和发票结清是不同维度，应分别建模，不能只依赖 paid 布尔判断净收入。
uncollectible：应收存在，但确认难以收回
uncollectible 用于将已 finalized 的发票标记为坏账。它表达的是应收账款无法收回，而不是把账单从历史中删除。财务报表、客户余额和 revenue recognition 的具体影响需按 Stripe 产品配置与会计政策核验。
不要在一次临时支付失败后立即标记 uncollectible。自动扣款可配置重试与催收，发送发票也可能尚未到期。只有业务已经完成催收判断并接受坏账结果时才使用。
若客户后来付款，Stripe 支持的状态转换与处理方式应以当前 workflow transitions 文档和实际对象为准。系统必须保留原坏账决定、后续付款来源和操作者，不能默默覆盖审计历史。
void：发票作废
void 表示该发票不再作为有效应收。常见原因是账单开错、订单取消，或需要重新开具正确发票。Void 与删除草稿不同：正式发票的编号和审计记录仍被保留，金额不再待收。
Void 不是退款。若 Invoice 已 paid 并产生 Charge，需要退款或 Credit Note 流程；不能通过 void 假装资金已退回。Stripe 对允许 void 的前置状态有明确转换规则，调用前应读取最新状态。
也不要用 void 表示客户暂时延期。延期应调整合法 due date、付款安排或催收策略；作废会改变应收语义。
paid、uncollectible 与 void 的区别
三者通常都是生命周期末端结果，但财务含义完全不同：paid 表示应收已结清；uncollectible 表示应收成为坏账；void 表示该发票被取消，不再构成应收。
运营界面不能把它们统一显示为“已关闭”。至少要展示状态、金额、结算来源、原因、时间和操作者。报表也不能用 status != open 当作收入。
状态转换应通过 Stripe 支持的 Invoice API 完成，并以 webhook/重新读取结果确认。直接在本地数据库改状态不会改变 Stripe 对象，也会造成对账分叉。
auto_advance=true 做什么
auto_advance=true 允许 Stripe 根据自动收款和发票工作流推进对象，例如自动 finalized、尝试付款、发送通知或执行配置的催收动作。确切行为取决于 collection method、账户设置和 Invoice 状态。
它不是“立刻付款”开关。Finalization 时间、webhook 交付、付款方式是否需要客户操作、重试策略和发送设置都会影响下一步。创建后应监听事件，而不是 sleep 数秒后假设 paid。
自动化减少应用编排代码，但仍需要失败监控。没有默认付款方式、税务配置错误或 webhook endpoint 持续失败，都可能阻断流程。
auto_advance=false 的真实含义
设置 auto_advance=false 会关闭 Stripe 对该发票的自动推进和收款自动化，常用于在 finalization 前执行自定义审核，或由应用完全控制发送与收款时机。
它不等于暂停整个 Subscription，也不会自动取消 Invoice。对象可能长期停留在 draft 或 open，直到应用调用 finalize、pay、send、void 等相应动作。
采用手动编排必须建立任务队列、幂等调用、重试、告警和人工兜底。否则一次 worker 故障就会产生永久草稿。切换 auto_advance 时还应核对下一次付款尝试和既有催收安排。
collection_method=charge_automatically
charge_ 表示 Stripe 在发票 finalized 后尝试使用客户的默认付款方式自动收款。它适合卡支付和其他支持相应自动收款流程的方式。
自动扣款可能成功、失败或要求客户完成认证。失败后是否重试、何时把 Subscription 标为 past_due/unpaid 或取消，取决于 Billing 的重试与订阅设置。Invoice status 与 Subscription status 会关联但不相同。
客户对象、Subscription 和 Invoice 都可能涉及付款方式设置。排障应确认最终用于该 Invoice 的 payment settings 与 default payment method，而不是只看客户历史卡片列表。
collection_method=send_invoice
send_invoice 表示向客户发送发票，让其在指定付款期限内主动付款。它适合 B2B 净账期、银行转账或需要采购审批的场景。Finalized 后通常通过 Hosted Invoice Page、邮件或 API 集成提供付款入口。
Stripe 是否自动发送邮件受账户邮件设置、创建方式和 API 调用影响。不能只设 collection_
Send Invoice 仍可通过 Stripe 记录付款和状态，但催款、到期处理和手动付款方式需要按账户设置设计。它不是“完全线下、Stripe 不参与”的同义词。
due_date 与 days_until_due
发送发票模式需要定义付款到期时间。创建或更新时可以使用绝对 due_date，或在适用 API 中使用相对 days_until_due 让 Stripe 从 finalization 等基准计算日期。两者的使用限制和互斥规则以当前 API 参考为准。
Due Date 不会在到达时自动证明付款失败。它只说明合同上的应付日期；逾期后的提醒、重试、Subscription 状态和坏账处理由催收配置及业务流程决定。
时区展示也要谨慎。Stripe 时间戳通常以 Unix time 表示，客户邮件与后台可能按账户或本地时区显示。应用应保存原始时间并在界面标明时区。
自动 finalized 为何可能延迟
Stripe 的自动推进会给 webhook endpoint 一定时间接收 invoice.created 等事件。官方自动 advancement 文档说明，若 webhook endpoint 未成功响应，自动 finalization 可能受到延迟。具体等待和重试行为应以当前文档为准。
因此 webhook 不只是通知旁路，它的健康度可能影响 Billing 自动化时序。Endpoint 必须快速验证签名、持久化 Event 并返回 2xx，耗时业务放入队列异步执行。
不要为了“让 finalize 快一点”忽略 webhook 签名或直接关闭重试。应监控 delivery attempts、响应时间、Event ID 去重和 dead-letter queue。
PaymentIntent 与 Invoice 的关系
Invoice 在需要在线收款时可能关联 PaymentIntent。PaymentIntent 管理付款尝试、认证和支付方式状态；Invoice 管理账单金额、行项目、到期、编号和整体应收状态。
一个 PaymentIntent succeeded 通常推动相应 Invoice paid，但 webhook 到达顺序可能不同。业务应按对象 ID 关联并读取最新 Invoice，而不是只根据事件顺序构造状态机。
若 Invoice 没有关联预期 PaymentIntent，先检查金额是否为零、客户余额、collection method、自动推进、支付设置和 Stripe API 版本，不要擅自创建第二个独立 PaymentIntent 造成重复收款。
重试、Dunning 与 Smart Retries
自动扣款失败后，Stripe Billing 可按配置执行重试和客户通知。Smart Retries 或自定义规则决定下一次尝试时间；最终 Subscription 与 Invoice 如何处理取决于自动化设置。
重试不是每个错误都适用。无有效付款方式、需要客户认证、卡永久拒绝和临时网络错误的处理不同。应用应展示可操作的失败原因，同时避免向客户暴露内部 decline 细节或敏感数据。
Webhook 处理必须容忍多次 invoice.payment_failed，不能每次都重复停服或发送无限邮件。以发票、attempt count 和业务动作表做幂等控制。
Hosted Invoice Page 与 Invoice PDF
Finalized Invoice 可提供 Hosted Invoice Page URL 和 PDF URL，供客户查看、下载或付款。URL 的可用性、过期行为和访问控制应以 Stripe 当前文档与对象字段为准。
不要把这些 URL 公开写入搜索可索引页面或长期日志。即使 URL 看似不可猜，也可能包含客户姓名、地址、金额和税号等敏感信息。应用应只在已授权客户会话中展示。
自己的“订单详情页”不是 Hosted Invoice Page 的替代财务凭证。若业务有法定发票要求，还需确认 Stripe Invoice 与当地税务票据的关系。
Webhook 事件如何映射
常见事件包括 invoice.created、invoice.、invoice.paid、invoice.payment_failed、invoice.marked_ 和 invoice.voided。事件描述某次变化，不是永远最新的对象快照。
处理步骤应是验证签名、按 Event ID 去重、记录接收、读取或使用受信任对象数据、执行幂等业务动作并保存结果。乱序时以后端当前 Invoice status 和允许状态转换为准。
不要只监听 payment_intent.succeeded 就认为所有 Subscription Invoice 已完成，也不要只监听 invoice.paid 而忽略退款与 dispute 的后续财务事件。
一套可执行的排障流程
- 记录 Invoice ID、Customer、Subscription 和 livemode；
- 读取当前 status、auto_advance 与 collection_
method； - 若 draft，检查 finalization error、webhook 和自动推进；
- 若 open，检查 due_date、attempt_count、next_
payment_ attempt 与 PaymentIntent； - 核对最终付款方式和客户是否需要认证；
- 查看所有相关 webhook delivery，而非只看应用日志；
- 区分自动扣款与发送发票的预期时序；
- 检查 Retry/Dunning 和 Subscription 状态规则；
- 对 paid/
uncollectible/ void 核对操作者、原因与资金事实； - 在 Sandbox/Test Clock 复现完整周期后再调整 Live 配置。
常见误区
draft 表示付款失败
错误。Draft 表示账单尚未 finalized，通常还没有进入正式收款阶段。
open 就是 past_due
错误。Open 只表示已 finalized 且未结清，可能尚未到期或正在处理付款。
void 等于 refund
错误。Void 作废应收账单；退款处理已经发生的资金流，两者不是同一动作。
auto_advance=false 会取消发票
错误。它关闭自动推进，发票仍存在并等待手动操作。
send_invoice 一定自动发邮件
错误。邮件发送还受账户设置和具体 API 流程影响，必须验证发送结果。
FAQ
1. Invoice 创建后为什么一直是 draft？
检查 auto_advance、finalization error、webhook endpoint 健康和是否由应用负责手动 finalize。
2. Finalize 后一定变成 open 吗？
通常如此，但零金额、客户余额等情况可能直接 paid，应读取 API 返回的真实状态。
3. Open Invoice 能否继续修改金额？
核心账单内容在 finalized 后受限。错误应通过 Stripe 支持的 Credit Note、void 或重开流程修正。
4. Paid 是否一定有成功 Charge？
不一定。零金额、客户余额或带外付款标记等路径也可能让 Invoice paid，需要检查付款来源字段。
5. 何时使用 uncollectible？
当业务确认应收无法收回并要记录坏账时使用，不应把一次临时付款失败立即视为坏账。
6. charge_automatically 失败后会怎样？
Stripe 可按 Billing 配置重试、通知并调整 Subscription 状态；具体动作取决于账户自动化规则。
7. due_date 适用于自动扣款吗？
它主要用于 send_invoice 的客户付款期限。自动扣款通常按 finalized 后的收款流程尝试。
8. 哪个事件最适合开通服务？
常见依据是幂等处理 invoice.paid 并读取最新 Invoice/