close
Core Resources
Payment Methods
Products
Commerce
Agentic Commerce
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury for Platforms
Payment Records
Account Evaluation
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

Subscription Schedules

A subscription schedule allows you to create and manage the lifecycle of a subscription by predefining expected changes.

Related guide: Subscription schedules

Was this section helpful?YesNo
Create a schedule
POST/v1/subscription_schedules
Update a schedule
POST/v1/subscription_schedules/:id
Retrieve a schedule
GET/v1/subscription_schedules/:id
List all schedules
GET/v1/subscription_schedules
Cancel a schedule
POST/v1/subscription_schedules/:id/cancel
Release a schedule
POST/v1/subscription_schedules/:id/release

The Subscription Schedule object

Attributes

  • idstring

    Unique identifier for the object.

  • current_phasenullable object

    Object representing the start and end dates for the current phase of the subscription schedule, if it is active.

  • customerstringExpandable

    ID of the customer who owns the subscription schedule.

  • metadatanullable map

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

  • phasesarray of objects

    Configuration for the subscription schedule’s phases.

  • statusenum

    The present status of the subscription schedule. Possible values are not_started, active, completed, released, and canceled. You can read more about the different states in our behavior guide.

    Possible enum values
    active
    canceled
    completed
    not_started
    released

  • subscriptionnullable stringExpandable

    ID of the subscription managed by the subscription schedule.

More attributes

  • objectstring

  • applicationnullable stringExpandableConnect only

  • billing_modeobject

  • canceled_atnullable timestamp

  • completed_atnullable timestamp

  • createdtimestamp

  • customer_accountnullable string

  • default_settingsobject

  • end_behaviorenum

  • livemodeboolean

  • released_atnullable timestamp

  • released_subscriptionnullable string

  • test_clocknullable stringExpandable

Create a schedule

POST /v1/subscription_schedules

Creates a new subscription schedule object. Each customer can have up to 500 active or scheduled subscriptions.

Parameters

  • customerstring

    The identifier of the customer to create the subscription schedule for.

  • metadatamap

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • phasesarray of objects

    List representing phases of the subscription schedule. Each phase can be customized to have different durations, plans, and coupons. If there are multiple phases, the end_date of one phase will always equal the start_date of the next phase.

  • start_datetimestamp | string, value is "now"

    When the subscription schedule starts. We recommend using now so that it starts the subscription immediately, and to avoid unexpected behavior due to request delays or clock skew resulting in a slightly backdated or postdated start. You can also use a Unix timestamp to backdate the subscription so that it starts on a past date, or set a future date for the subscription to start on.

More parameters

  • billing_modeobject

  • customer_accountstring

  • default_settingsobject

  • end_behaviorenum

  • from_subscriptionstring

Returns

Returns a subscription schedule object if the call succeeded.

curl https://api.stripe.com/v1/subscription_schedules \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d customer= \
  -d start_date=1787130418 \
  -d end_behavior=release \
  -d "phases[0][items][0][price]=" \
  -d "phases[0][items][0][quantity]=1" \
  -d "phases[0][duration][interval]=month" \
  -d "phases[0][duration][interval_count]=1"
Response
{
  "id": "",
  "object": "subscription_schedule",
  "application": null,
  "canceled_at": null,
  "completed_at": null,
  "created": 1724058651,
  "current_phase": null,
  "customer": "",
  "default_settings": {
    "application_fee_percent": null,
    "automatic_tax": {
      "enabled": false,
      "liability": null
    },
    "billing_cycle_anchor": "automatic",
    "collection_method": "charge_automatically",
    "default_payment_method": null,
    "default_source": null,
    "description": null,
    "invoice_settings": {
      "issuer": {
        "type": "self"
      }
    },
    "on_behalf_of": null,
    "transfer_data": null
  },
  "end_behavior": "release",
  "livemode": false,
  "metadata": {},
  "phases": [
    {
      "add_invoice_items": [],
      "application_fee_percent": null,
      "billing_cycle_anchor": null,
      "collection_method": null,
      "currency": "usd",
      "default_payment_method": null,
      "default_tax_rates": [],
      "description": null,
      "discounts": null,
      "end_date": 1818666418,
      "invoice_settings": null,
      "items": [
        {
          "discounts": null,
          "metadata": {},
          "plan": "",
          "price": "",
          "quantity": 1,
          "tax_rates": []
        }
      ],
      "metadata": {},
      "on_behalf_of": null,
      "proration_behavior": "create_prorations",
      "start_date": 1787130418,
      "transfer_data": null,
      "trial_end": null
    }
  ],
  "released_at": null,
  "released_subscription": null,
  "renewal_interval": null,
  "status": "not_started",
  "subscription": null,
  "test_clock": null
}