# subscription\_schedule

From **Stripe API**.

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

- Type: `object`

## Properties

### `canceled_at`

- Required: false
- Type: `integer`
- Format: `unix-time`
- Nullable: true

Time at which the subscription schedule was canceled. Measured in seconds since the Unix epoch.

### `completed_at`

- Required: false
- Type: `integer`
- Format: `unix-time`
- Nullable: true

Time at which the subscription schedule was completed. Measured in seconds since the Unix epoch.

### `created`

- Required: true
- Type: `integer`
- Format: `unix-time`

Time at which the object was created. Measured in seconds since the Unix epoch.

### `current_phase`

- Required: false
- Nullable: true

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

### `customer`

- Required: true
ID of the customer who owns the subscription schedule.

### `default_settings`

- Required: true
- Type: `object`

### `end_behavior`

- Required: true
- Type: `string`
- Allowed values: `"cancel"`, `"none"`, `"release"`, `"renew"`

Behavior of the subscription schedule and underlying subscription when it ends. Possible values are `release` and `cancel`.

### `id`

- Required: true
- Type: `string`
- maxLength: `5000`

Unique identifier for the object.

### `livemode`

- Required: true
- Type: `boolean`

Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.

### `metadata`

- Required: false
- Type: `object`
- Nullable: true

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.

### `object`

- Required: true
- Type: `string`
- Allowed values: `"subscription_schedule"`

String representing the object's type. Objects of the same type share the same value.

### `phases`

- Required: true
- Type: `array`

Configuration for the subscription schedule's phases.

### `released_at`

- Required: false
- Type: `integer`
- Format: `unix-time`
- Nullable: true

Time at which the subscription schedule was released. Measured in seconds since the Unix epoch.

### `released_subscription`

- Required: false
- Type: `string`
- Nullable: true
- maxLength: `5000`

ID of the subscription once managed by the subscription schedule (if it is released).

### `status`

- Required: true
- Type: `string`
- Allowed values: `"active"`, `"canceled"`, `"completed"`, `"not_started"`, `"released"`

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

### `subscription`

- Required: false
- Nullable: true

ID of the subscription managed by the subscription schedule.

## JSON Schema

```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"}
```