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

Update a schedule

POST /v1/subscription_schedules/:id

Updates an existing subscription schedule.

Parameters

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

  • proration_behaviorenum

    If the update changes the billing configuration (item price, quantity, etc.) of the current phase, indicates how prorations from this change should be handled. 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.

curl https://api.stripe.com/v1/subscription_schedules/ \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d end_behavior=release
Response
{
  "id": "",
  "object": "subscription_schedule",
  "application": null,
  "canceled_at": null,
  "completed_at": null,
  "created": 1680113835,
  "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,
      "end_date": 1712339228,
      "invoice_settings": null,
      "items": [
        {
          "metadata": {},
          "plan": "",
          "price": "",
          "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

GET /v1/subscription_schedules/:id

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.

curl https://api.stripe.com/v1/subscription_schedules/ \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
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
}

List all schedules

GET /v1/subscription_schedules

Retrieves the list of your subscription schedules.

Parameters

  • customerstring

    Only return subscription schedules for the given customer. The response will not include subscription schedules for customers with a test clock attached if this parameter is not set.

More parameters

  • canceled_atobject

  • completed_atobject

  • createdobject

  • customer_accountstring

  • 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.

curl -G https://api.stripe.com/v1/subscription_schedules \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d limit=3
Response
{
  "object": "list",
  "url": "/v1/subscription_schedules",
  "has_more": false,
  "data": [
    {
      "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
    }
  ]
}