Create a schedule

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.

metadataobject
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
When the subscription schedule starts. We recommend using now so that it starts the subscription immediately. 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

default_settingsobject

end_behaviorenum

from_subscriptionstring

Returns

Returns a subscription schedule object if the call succeeded.

POST /v1/subscription_schedules

Server-side language

curl https://api.stripe.com/v1/subscription_schedules \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d customer=cus_NcI8FsMbh0OeFs \
  -d start_date=1787130418 \
  -d end_behavior=release \
  -d "phases[0][items][0][price]"=price_1Mr3YcLkdIwHu7ixYCFhXHNb \
  -d "phases[0][items][0][quantity]"=1 \
  -d "phases[0][iterations]"=12

Response

{
  "id": "sub_sched_1Mr3YdLkdIwHu7ixjop3qtff",
  "object": "subscription_schedule",
  "application": null,
  "canceled_at": null,
  "completed_at": null,
  "created": 1724058651,
  "current_phase": null,
  "customer": "cus_NcI8FsMbh0OeFs",
  "default_settings": {
    "application_fee_percent": null,
    "automatic_tax": {
      "enabled": false,
      "liability": null
    },
    "billing_cycle_anchor": "automatic",
    "billing_thresholds": null,
    "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,
      "billing_thresholds": null,
      "collection_method": null,
      "coupon": null,
      "currency": "usd",
      "default_payment_method": null,
      "default_tax_rates": [],
      "description": null,
      "discounts": null,
      "end_date": 1818666418,
      "invoice_settings": null,
      "items": [
        {
          "billing_thresholds": null,
          "discounts": null,
          "metadata": {},
          "plan": "price_1Mr3YcLkdIwHu7ixYCFhXHNb",
          "price": "price_1Mr3YcLkdIwHu7ixYCFhXHNb",
          "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
}

Update a schedule

Updates an existing subscription schedule.

Parameters

metadataobject
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. Note that past phases can be omitted.

proration_behaviorenum

If the update changes the current phase, indicates whether the changes should be prorated. The default value is create_prorations.

Possible enum values

always_invoice

Prorate changes, and force an invoice to be immediately created for any prorations.

create_prorations

Prorate changes, but leave any prorations as pending invoice items to be picked up on the customer’s next invoice.

none

Does not create any prorations.

More parameters

default_settingsobject

end_behaviorenum

Returns

Returns an updated subscription schedule object if the call succeeded.

POST /v1/subscription_schedules/:id

Server-side language

curl https://api.stripe.com/v1/subscription_schedules/sub_sched_1Mr3YdLkdIwHu7ixjop3qtff \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d end_behavior=release

Response

{
  "id": "sub_sched_1Mr3YdLkdIwHu7ixjop3qtff",
  "object": "subscription_schedule",
  "application": null,
  "canceled_at": null,
  "completed_at": null,
  "created": 1680113835,
  "current_phase": null,
  "customer": "cus_NcI8FsMbh0OeFs",
  "default_settings": {
    "application_fee_percent": null,
    "automatic_tax": {
      "enabled": false,
      "liability": null
    },
    "billing_cycle_anchor": "automatic",
    "billing_thresholds": null,
    "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,
      "billing_thresholds": null,
      "collection_method": null,
      "coupon": null,
      "currency": "usd",
      "default_payment_method": null,
      "default_tax_rates": [],
      "description": null,
      "end_date": 1712339228,
      "invoice_settings": null,
      "items": [
        {
          "billing_thresholds": null,
          "metadata": {},
          "plan": "price_1Mr3YcLkdIwHu7ixYCFhXHNb",
          "price": "price_1Mr3YcLkdIwHu7ixYCFhXHNb",
          "quantity": 1,
          "tax_rates": []
        }
      ],
      "metadata": {},
      "on_behalf_of": null,
      "proration_behavior": "create_prorations",
      "start_date": 1680716828,
      "transfer_data": null,
      "trial_end": null
    }
  ],
  "released_at": null,
  "released_subscription": null,
  "renewal_interval": null,
  "status": "not_started",
  "subscription": null,
  "test_clock": null
}

Retrieve a schedule

Retrieves the details of an existing subscription schedule. You only need to supply the unique subscription schedule identifier that was returned upon subscription schedule creation.

Parameters

No parameters.

Returns

Returns a subscription schedule object if a valid identifier was provided.

GET /v1/subscription_schedules/:id

Server-side language

curl https://api.stripe.com/v1/subscription_schedules/sub_sched_1Mr3YdLkdIwHu7ixjop3qtff \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"

Response

{
  "id": "sub_sched_1Mr3YdLkdIwHu7ixjop3qtff",
  "object": "subscription_schedule",
  "application": null,
  "canceled_at": null,
  "completed_at": null,
  "created": 1724058651,
  "current_phase": null,
  "customer": "cus_NcI8FsMbh0OeFs",
  "default_settings": {
    "application_fee_percent": null,
    "automatic_tax": {
      "enabled": false,
      "liability": null
    },
    "billing_cycle_anchor": "automatic",
    "billing_thresholds": null,
    "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,
      "billing_thresholds": null,
      "collection_method": null,
      "coupon": null,
      "currency": "usd",
      "default_payment_method": null,
      "default_tax_rates": [],
      "description": null,
      "discounts": null,
      "end_date": 1818666418,
      "invoice_settings": null,
      "items": [
        {
          "billing_thresholds": null,
          "discounts": null,
          "metadata": {},
          "plan": "price_1Mr3YcLkdIwHu7ixYCFhXHNb",
          "price": "price_1Mr3YcLkdIwHu7ixYCFhXHNb",
          "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
}

List all schedules

Retrieves the list of your subscription schedules.

Parameters

customerstring
Only return subscription schedules for the given customer.

More parameters

canceled_atobject

completed_atobject

createdobject

ending_beforestring

limitinteger

released_atobject

scheduledboolean

starting_afterstring

Returns

A dictionary with a data property that contains an array of up to limit subscription schedules, starting after subscription schedule starting_after. Each entry in the array is a separate subscription schedule object. If no more subscription schedules are available, the resulting array will be empty.

GET /v1/subscription_schedules

Server-side language

curl -G https://api.stripe.com/v1/subscription_schedules \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d limit=3

Response

{
  "object": "list",
  "url": "/v1/subscription_schedules",
  "has_more": false,
  "data": [
    {
      "id": "sub_sched_1Mr3YdLkdIwHu7ixjop3qtff",
      "object": "subscription_schedule",
      "application": null,
      "canceled_at": null,
      "completed_at": null,
      "created": 1724058651,
      "current_phase": null,
      "customer": "cus_NcI8FsMbh0OeFs",
      "default_settings": {
        "application_fee_percent": null,
        "automatic_tax": {
          "enabled": false,
          "liability": null
        },
        "billing_cycle_anchor": "automatic",
        "billing_thresholds": null,
        "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,
          "billing_thresholds": null,
          "collection_method": null,
          "coupon": null,
          "currency": "usd",
          "default_payment_method": null,
          "default_tax_rates": [],
          "description": null,
          "discounts": null,
          "end_date": 1818666418,
          "invoice_settings": null,
          "items": [
            {
              "billing_thresholds": null,
              "discounts": null,
              "metadata": {},
              "plan": "price_1Mr3YcLkdIwHu7ixYCFhXHNb",
              "price": "price_1Mr3YcLkdIwHu7ixYCFhXHNb",
              "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
    }
  ]
}

Cancel a schedule

Cancels a subscription schedule and its associated subscription immediately (if the subscription schedule has an active subscription). A subscription schedule can only be canceled if its status is not_started or active.

Parameters

invoice_nowboolean
If the subscription schedule is active, indicates if a final invoice will be generated that contains any un-invoiced metered usage and new/pending proration invoice items. Defaults to true.

More parameters

prorateboolean

Returns

The canceled subscription_schedule object. Its status will be canceled and canceled_at will be the current time.

POST /v1/subscription_schedules/:id/cancel

Server-side language

curl -X POST https://api.stripe.com/v1/subscription_schedules/sub_sched_1Mr3owLkdIwHu7ix38CXMudt/cancel \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"

Response

{
  "id": "sub_sched_1Mr3owLkdIwHu7ix38CXMudt",
  "object": "subscription_schedule",
  "application": null,
  "canceled_at": 1680114847,
  "completed_at": null,
  "created": 1680114846,
  "current_phase": null,
  "customer": "cus_NcIPFRC981NmaY",
  "default_settings": {
    "application_fee_percent": null,
    "automatic_tax": {
      "enabled": false,
      "liability": null
    },
    "billing_cycle_anchor": "automatic",
    "billing_thresholds": null,
    "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,
      "billing_thresholds": null,
      "collection_method": null,
      "coupon": null,
      "currency": "usd",
      "default_payment_method": null,
      "default_tax_rates": [],
      "description": null,
      "end_date": 1712339228,
      "invoice_settings": null,
      "items": [
        {
          "billing_thresholds": null,
          "metadata": {},
          "plan": "price_1Mr3owLkdIwHu7ix0RyYpQzk",
          "price": "price_1Mr3owLkdIwHu7ix0RyYpQzk",
          "quantity": 1,
          "tax_rates": []
        }
      ],
      "metadata": {},
      "on_behalf_of": null,
      "proration_behavior": "create_prorations",
      "start_date": 1680716828,
      "transfer_data": null,
      "trial_end": null
    }
  ],
  "released_at": null,
  "released_subscription": null,
  "renewal_interval": null,
  "status": "canceled",
  "subscription": null,
  "test_clock": null
}

Create a schedule

Parameters

customerstring

metadataobject

phasesarray of objects

start_datetimestamp | string

More parametersExpand all

default_settingsobject

end_behaviorenum

from_subscriptionstring

Returns

Update a schedule

Parameters

metadataobject

phasesarray of objects

proration_behaviorenum

More parametersExpand all

default_settingsobject

end_behaviorenum

Returns

Retrieve a schedule

Parameters

Returns

List all schedules

Parameters

customerstring

More parametersExpand all

canceled_atobject

completed_atobject

createdobject

ending_beforestring

limitinteger

released_atobject

scheduledboolean

starting_afterstring

Returns

Cancel a schedule

Parameters

invoice_nowboolean

More parametersExpand all

prorateboolean

Returns

More parameters

More parameters

More parameters

More parameters