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 thestart_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.
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 thestart_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
.
More parameters
- default_
settingsobject - end_
behaviorenum
Returns
Returns an updated subscription schedule object if the call succeeded.
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.
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.
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 totrue
.
More parameters
- prorateboolean
Returns
The canceled subscription_schedule
object. Its status will be canceled
and canceled_at
will be the current time.