{
  "slug": "stripe-invoice-preview-supports-subscription-pauses-06f65aeb5a26",
  "title": "Stripe invoice preview supports subscription pauses",
  "tools": [
    "stripe"
  ],
  "tags": [
    "agent"
  ],
  "introduced_at": "2026-06-24T00:00:00.000Z",
  "announced_at": "2026-06-24T00:00:00.000Z",
  "effective_at": null,
  "date_basis": "source-publication",
  "status": "unknown",
  "how": {
    "incantation": "When previewing a subscription pause, create a preview invoice with `subscription_details.pause`, `invoicing_behavior=invoice`, and `bill_for` settings that produce billable unused time or metered usage. Use the returned preview invoice and expanded projected subscription state; the preview does not modify the subscription.",
    "examples": [
      "curl https://api.stripe.com/v1/invoices/create_preview \\\n  -u \"<<YOUR_SECRET_KEY>>:\" \\\n  -d subscription=<SUBSCRIPTION_ID> \\\n  -d \"subscription_details[pause][invoicing_behavior]=invoice\" \\\n  -d \"subscription_details[pause][bill_for][unused_time_from][type]=now\" \\\n  -d \"subscription_details[pause][bill_for][outstanding_usage_through][type]=now\" \\\n  -d \"expand[]=parent.subscription_details.subscription\""
    ],
    "gotchas": [
      "Availability: Preview API version 2026-06-24.preview",
      "subscription (required): Subscription identifier for the upcoming invoice preview.",
      "subscription_details.pause.invoicing_behavior (required): Set to `invoice` to receive a preview invoice; `pending_invoice_item` returns 404.",
      "subscription_details.pause.bill_for.unused_time_from.type (required): `now` credits unused licensed time from pause time; `item_current_period_start` credits from each item's period start; `none` does not credit unused time.",
      "subscription_details.pause.bill_for.outstanding_usage_through.type (required): `now` bills metered usage from current period start through pause time; `none` does not bill current-period metered usage.",
      "expand[]: Set to `parent.subscription_details.subscription` to see the projected subscription state after pausing; these changes do not persist.",
      "Prerequisite: For a restricted API key, grant `invoice_read` to preview invoices.",
      "Prerequisite: A valid subscription/customer must be provided; preview invoice creation requires valid customer information.",
      "`invoicing_behavior` must be `invoice` to receive a preview invoice; `pending_invoice_item` returns a 404 error.",
      "`bill_for` must produce billable amounts for unused licensed time or outstanding metered usage; if pausing would not create debits or credits, the endpoint returns a 404 error."
    ]
  },
  "why_it_matters": "When implementing subscription pausing, preview the billing impact and projected subscription state before changing the subscription.",
  "sources": [
    "https://docs.stripe.com/changelog/dahlia/2026-06-24/preview-invoices-before-pausing-subscription",
    "https://docs.stripe.com/billing/subscriptions/pause#preview-the-invoice-before-pausing",
    "https://docs.stripe.com/api/invoices/create_preview?api-version=2026-06-24.preview",
    "https://docs.stripe.com/billing/subscriptions/pause#how-pausing-affects-billing",
    "https://docs.stripe.com/billing/subscriptions/pause#before-you-begin"
  ],
  "rank": 0.97036,
  "judge": {
    "publish": true,
    "judge_model": "codex-cli/gpt-6-luna+typesafe/jev-1.13.0",
    "prompt_version": "extract-v7+enrich-v2+judge-v2x3+jev-publish-v1"
  },
  "review_state": "approved",
  "provenance": {
    "run_id": "wave1b-tools-20261017",
    "verdict_id": "wave1b-tools-20261017:wave1b-tools-20261017-4570b675073511b8-0:gate",
    "evidence_hash": "b637f4603c7067ac715d0e1690b71749eb9106e20c359e81bad46bea052f79e2"
  },
  "review": {
    "draft_hash": "e89e73fadbe1d9a6b8170e3e32cc208d012dcdd9f65b80e5e77232a016610b06",
    "reviewer": "publication-gate",
    "reviewed_at": "2026-10-07T00:00:00.000Z",
    "decision": "wave1b-tools-20261017:gate",
    "reason": "3 of 3 judge runs approved with p_yes >= 0.9 (mean 0.97 >= 0.9; 2 needed) and Jev gave 0.69 (>= 0.6 needed)."
  }
}