# PostSubscriptionSchedulesSchedule From **Stripe API**. `POST /v1/subscription_schedules/{schedule}`

Updates an existing subscription schedule.

## Parameters ### `schedule` - Location: path - Required: true - Type: `string` - maxLength: `5000` ## Request body - Required: false ### `application/x-www-form-urlencoded` - Type: `object` ```json {"additionalProperties":false,"properties":{"default_settings":{"description":"Object representing the subscription schedule's default settings.","properties":{"application_fee_percent":{"type":"number"},"automatic_tax":{"properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"title":"automatic_tax_config","type":"object"},"billing_cycle_anchor":{"enum":["automatic","phase_start"],"type":"string"},"billing_thresholds":{"anyOf":[{"properties":{"amount_gte":{"type":"integer"},"reset_billing_cycle_anchor":{"type":"boolean"}},"title":"billing_thresholds_param","type":"object"},{"enum":[""],"type":"string"}]},"collection_method":{"enum":["charge_automatically","send_invoice"],"type":"string"},"default_payment_method":{"maxLength":5000,"type":"string"},"invoice_settings":{"properties":{"days_until_due":{"type":"integer"}},"title":"subscription_schedules_param","type":"object"},"transfer_data":{"anyOf":[{"properties":{"amount_percent":{"type":"number"},"destination":{"type":"string"}},"required":["destination"],"title":"transfer_data_specs","type":"object"},{"enum":[""],"type":"string"}]}},"title":"default_settings_params","type":"object"},"end_behavior":{"description":"Configures how the subscription schedule behaves when it ends. Possible values are `release` or `cancel` with the default being `release`. `release` will end the subscription schedule and keep the underlying subscription running.`cancel` will end the subscription schedule and cancel the underlying subscription.","enum":["cancel","none","release","renew"],"type":"string"},"expand":{"description":"Specifies which fields in the response should be expanded.","items":{"maxLength":5000,"type":"string"},"type":"array"},"metadata":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"enum":[""],"type":"string"}],"description":"Set of [key-value pairs](https://stripe.com/docs/api/metadata) 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`."},"phases":{"description":"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.","items":{"properties":{"add_invoice_items":{"items":{"properties":{"price":{"maxLength":5000,"type":"string"},"price_data":{"properties":{"currency":{"type":"string"},"product":{"maxLength":5000,"type":"string"},"tax_behavior":{"enum":["exclusive","inclusive","unspecified"],"type":"string"},"unit_amount":{"type":"integer"},"unit_amount_decimal":{"format":"decimal","type":"string"}},"required":["currency","product"],"title":"one_time_price_data","type":"object"},"quantity":{"type":"integer"},"tax_rates":{"anyOf":[{"items":{"maxLength":5000,"type":"string"},"type":"array"},{"enum":[""],"type":"string"}]}},"title":"add_invoice_item_entry","type":"object"},"type":"array"},"application_fee_percent":{"type":"number"},"automatic_tax":{"properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"title":"automatic_tax_config","type":"object"},"billing_cycle_anchor":{"enum":["automatic","phase_start"],"type":"string"},"billing_thresholds":{"anyOf":[{"properties":{"amount_gte":{"type":"integer"},"reset_billing_cycle_anchor":{"type":"boolean"}},"title":"billing_thresholds_param","type":"object"},{"enum":[""],"type":"string"}]},"collection_method":{"enum":["charge_automatically","send_invoice"],"type":"string"},"coupon":{"maxLength":5000,"type":"string"},"default_payment_method":{"maxLength":5000,"type":"string"},"default_tax_rates":{"anyOf":[{"items":{"maxLength":5000,"type":"string"},"type":"array"},{"enum":[""],"type":"string"}]},"end_date":{"anyOf":[{"type":"integer"},{"enum":["now"],"maxLength":5000,"type":"string"}]},"invoice_settings":{"properties":{"days_until_due":{"type":"integer"}},"title":"subscription_schedules_param","type":"object"},"items":{"items":{"properties":{"billing_thresholds":{"anyOf":[{"properties":{"usage_gte":{"type":"integer"}},"required":["usage_gte"],"title":"item_billing_thresholds_param","type":"object"},{"enum":[""],"type":"string"}]},"price":{"maxLength":5000,"type":"string"},"price_data":{"properties":{"currency":{"type":"string"},"product":{"maxLength":5000,"type":"string"},"recurring":{"properties":{"interval":{"enum":["day","month","week","year"],"type":"string"},"interval_count":{"type":"integer"}},"required":["interval"],"title":"recurring_adhoc","type":"object"},"tax_behavior":{"enum":["exclusive","inclusive","unspecified"],"type":"string"},"unit_amount":{"type":"integer"},"unit_amount_decimal":{"format":"decimal","type":"string"}},"required":["currency","product","recurring"],"title":"recurring_price_data","type":"object"},"quantity":{"type":"integer"},"tax_rates":{"anyOf":[{"items":{"maxLength":5000,"type":"string"},"type":"array"},{"enum":[""],"type":"string"}]}},"title":"configuration_item_params","type":"object"},"type":"array"},"iterations":{"type":"integer"},"proration_behavior":{"enum":["always_invoice","create_prorations","none"],"type":"string"},"start_date":{"anyOf":[{"type":"integer"},{"enum":["now"],"maxLength":5000,"type":"string"}]},"transfer_data":{"properties":{"amount_percent":{"type":"number"},"destination":{"type":"string"}},"required":["destination"],"title":"transfer_data_specs","type":"object"},"trial":{"type":"boolean"},"trial_end":{"anyOf":[{"type":"integer"},{"enum":["now"],"maxLength":5000,"type":"string"}]}},"required":["items"],"title":"phase_configuration_params","type":"object"},"type":"array"},"proration_behavior":{"description":"If the update changes the current phase, indicates if the changes should be prorated. Possible values are `create_prorations` or `none`, and the default value is `create_prorations`.","enum":["always_invoice","create_prorations","none"],"type":"string"}},"type":"object"} ``` ## Security ### `basicAuth` - Type: `http` - Request header: `Authorization` - Scheme: `basic` Send credentials in the `Authorization` request header using the `Basic` scheme. Basic HTTP authentication. Allowed headers-- Authorization: Basic | Authorization: Basic ### `bearerAuth` - Type: `http` - Request header: `Authorization` - Scheme: `bearer` - Bearer format: `auth-scheme` Send the token in the `Authorization` request header using the `Bearer` scheme. Bearer HTTP authentication. Allowed headers-- Authorization: Bearer ## Responses ### `200` Successful response. ### `application/json` - Type: `object` A subscription schedule allows you to create and manage the lifecycle of a subscription by predefining expected changes. Related guide: [Subscription Schedules](https://stripe.com/docs/billing/subscriptions/subscription-schedules). ```json {"description":"A subscription schedule allows you to create and manage the lifecycle of a subscription by predefining expected changes.\n\nRelated guide: [Subscription Schedules](https://stripe.com/docs/billing/subscriptions/subscription-schedules).","properties":{"canceled_at":{"description":"Time at which the subscription schedule was canceled. Measured in seconds since the Unix epoch.","format":"unix-time","nullable":true,"type":"integer"},"completed_at":{"description":"Time at which the subscription schedule was completed. Measured in seconds since the Unix epoch.","format":"unix-time","nullable":true,"type":"integer"},"created":{"description":"Time at which the object was created. Measured in seconds since the Unix epoch.","format":"unix-time","type":"integer"},"current_phase":{"anyOf":[{"$ref":"#/components/schemas/subscription_schedule_current_phase"}],"description":"Object representing the start and end dates for the current phase of the subscription schedule, if it is `active`.","nullable":true},"customer":{"anyOf":[{"maxLength":5000,"type":"string"},{"$ref":"#/components/schemas/customer"},{"$ref":"#/components/schemas/deleted_customer"}],"description":"ID of the customer who owns the subscription schedule.","x-expansionResources":{"oneOf":[{"$ref":"#/components/schemas/customer"},{"$ref":"#/components/schemas/deleted_customer"}]}},"default_settings":{"$ref":"#/components/schemas/subscription_schedules_resource_default_settings"},"end_behavior":{"description":"Behavior of the subscription schedule and underlying subscription when it ends. Possible values are `release` and `cancel`.","enum":["cancel","none","release","renew"],"type":"string"},"id":{"description":"Unique identifier for the object.","maxLength":5000,"type":"string"},"livemode":{"description":"Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.","type":"boolean"},"metadata":{"additionalProperties":{"maxLength":500,"type":"string"},"description":"Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.","nullable":true,"type":"object"},"object":{"description":"String representing the object's type. Objects of the same type share the same value.","enum":["subscription_schedule"],"type":"string"},"phases":{"description":"Configuration for the subscription schedule's phases.","items":{"$ref":"#/components/schemas/subscription_schedule_phase_configuration"},"type":"array"},"released_at":{"description":"Time at which the subscription schedule was released. Measured in seconds since the Unix epoch.","format":"unix-time","nullable":true,"type":"integer"},"released_subscription":{"description":"ID of the subscription once managed by the subscription schedule (if it is released).","maxLength":5000,"nullable":true,"type":"string"},"status":{"description":"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](https://stripe.com/docs/billing/subscriptions/subscription-schedules).","enum":["active","canceled","completed","not_started","released"],"type":"string"},"subscription":{"anyOf":[{"maxLength":5000,"type":"string"},{"$ref":"#/components/schemas/subscription"}],"description":"ID of the subscription managed by the subscription schedule.","nullable":true,"x-expansionResources":{"oneOf":[{"$ref":"#/components/schemas/subscription"}]}}},"required":["created","customer","default_settings","end_behavior","id","livemode","object","phases","status"],"title":"SubscriptionSchedule","type":"object","x-expandableFields":["current_phase","customer","default_settings","phases","subscription"],"x-resourceId":"subscription_schedule"} ``` ### `default` Error response. ### `application/json` - Type: `object` An error response from the Stripe API ```json {"description":"An error response from the Stripe API","properties":{"error":{"$ref":"#/components/schemas/api_errors"}},"required":["error"],"type":"object"} ``` ## Request examples ### cURL ```shell curl --request POST \ --url https://api.stripe.com/v1/subscription_schedules/{schedule} \ --header 'content-type: application/x-www-form-urlencoded' \ --data '{ "default_settings": { "application_fee_percent": 1, "automatic_tax": { "enabled": true }, "billing_cycle_anchor": "string", "billing_thresholds": "string", "collection_method": "string", "default_payment_method": "string", "invoice_settings": { "days_until_due": 1 }, "transfer_data": "string" }, "end_behavior": "string", "expand": [ "string" ], "metadata": "string", "phases": [ { "add_invoice_items": [ { "price": "string", "price_data": { "currency": "string", "product": "string", "tax_behavior": "string", "unit_amount": 1, "unit_amount_decimal": "string" }, "quantity": 1, "tax_rates": "string" } ], "application_fee_percent": 1, "automatic_tax": { "enabled": true }, "billing_cycle_anchor": "string", "billing_thresholds": "string", "collection_method": "string", "coupon": "string", "default_payment_method": "string", "default_tax_rates": "string", "end_date": "string", "invoice_settings": { "days_until_due": 1 }, "items": [ { "billing_thresholds": "string", "price": "string", "price_data": { "currency": "string", "product": "string", "recurring": { "interval": "string", "interval_count": 1 }, "tax_behavior": "string", "unit_amount": 1, "unit_amount_decimal": "string" }, "quantity": 1, "tax_rates": "string" } ], "iterations": 1, "proration_behavior": "string", "start_date": "string", "transfer_data": { "amount_percent": 1, "destination": "string" }, "trial": true, "trial_end": "string" } ], "proration_behavior": "string" }' ```