{
  "slug": "stripe-subscriptions-support-billing-schedules-for-prebilling-future-periods-f2717dc788a8",
  "title": "Stripe subscriptions support billing schedules for prebilling future periods",
  "tools": [
    "stripe"
  ],
  "tags": [
    "agent"
  ],
  "introduced_at": "2026-05-27T00:00:00.000Z",
  "announced_at": "2026-05-27T00:00:00.000Z",
  "effective_at": null,
  "date_basis": "source-publication",
  "status": "unknown",
  "how": {
    "incantation": "When prebilling subscription periods, use `billing_schedules` on create or update to set the end date and target items. Read each subscription item's `billed_until` to see when its prebilled period ends.",
    "examples": [
      "curl https://api.stripe.com/v1/subscriptions -u \"<<YOUR_SECRET_KEY>>:\" -d \"customer={{CUSTOMER_ID}}\" -d \"items[0][price]={{PRICE_ID}}\" -d \"billing_mode[type]=flexible\" -d \"billing_schedules[0][bill_until][type]=duration\" -d \"billing_schedules[0][bill_until][duration][interval]=month\" -d \"billing_schedules[0][bill_until][duration][interval_count]=2\"",
      "curl https://api.stripe.com/v1/subscriptions/{{SUBSCRIPTION_ID}} -u \"<<YOUR_SECRET_KEY>>:\" -d \"billing_schedules[0][bill_until][type]=duration\" -d \"billing_schedules[0][bill_until][duration][interval]=month\" -d \"billing_schedules[0][bill_until][duration][interval_count]=2\""
    ],
    "gotchas": [
      "billing_schedules: Array of billing schedule objects for the subscription.",
      "billing_schedules[].applies_to[].type: Use `price` to target items by price; omit `applies_to` to prebill all applicable licensed-price items.",
      "billing_schedules[].applies_to[].price: Price ID of an item to prebill when `type=price`.",
      "billing_schedules[].bill_until.type (required): Select `duration` or `timestamp`; these alternatives are mutually exclusive.",
      "billing_schedules[].bill_until.duration.interval (required): Duration unit, such as `month`.",
      "billing_schedules[].bill_until.duration.interval_count (required): Number of duration units.",
      "billing_schedules[].bill_until.timestamp (required): Unix timestamp for the prebilling end date when `type=timestamp`.",
      "billing_schedules[].proration_behavior: Controls invoice timing: `always_invoice` generates the prebilling invoice immediately; `create_prorations` generates it at the next natural billing cycle.",
      "billing_mode[type] (required): Set to `flexible`; prebilling requires flexible billing mode.",
      "billed_until: Subscription item property showing when that item's prebilled period ends.",
      "Prerequisite: Prebilling requires flexible billing mode and API version `2026-05-27.dahlia` or later.",
      "Prerequisite: For an existing subscription, it must already use `billing_mode=flexible`.",
      "Billing schedules can apply to some or all items in a subscription.",
      "Docs conflict: The release note says billing schedules can apply to some or all subscription items. The prebilling guide narrows this: all-item prebilling covers applicable licensed-price items; usage-based prices are excluded. The guide also says prebilling cannot be used with subscription schedules or subscriptions backed by one."
    ]
  },
  "why_it_matters": "When implementing subscription billing that collects payment before a future period begins, create, update, or preview the subscription with a billing schedule and inspect each item's billed_until value.",
  "sources": [
    "https://docs.stripe.com/changelog/dahlia/2026-05-27/subscriptions-billing-schedules",
    "https://docs.stripe.com/billing/subscriptions/prebilling",
    "https://docs.stripe.com/api/subscriptions/create?api-version=2026-05-27.dahlia"
  ],
  "rank": 0.99039,
  "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-72b5c9c45890aaea-0:gate",
    "evidence_hash": "2705d65c66503e915f9465b74a548572269a616b041354b62aa7776496058dbc"
  },
  "review": {
    "draft_hash": "5acd0253defc98a9c62594a539cb2a303e69e76557bc46f9b08a67a11eeaec4c",
    "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.99 >= 0.9; 2 needed) and Jev gave 0.70 (>= 0.6 needed)."
  }
}