Schedule API

Schedules allow you to plan events at regular intervals in the future. For example, you can charge a customer every month or transfer your balance to your account every Monday.


Name Type Description
object string

The string schedule.

id object_id


livemode boolean

Whether this is a live (true) or test (false) schedule.

location string

Path to retrieve the schedule.

status string

One of:

  • active: The schedule is running.
  • expiring: The schedule's next occurrence is its last.
  • expired: The schedule has reached its last occurrence and is not running anymore.
  • deleted: The schedule has been deleted and is not running anymore.
  • suspended: The schedule could not be completed and was stopped.

every integer

How often the schedule runs. E.g.: Every 3 weeks.

period string

day, week or month. E.g.: Every 3 weeks

on[weekdays] Array

Only for the week period. An array of weekday names. E.g.: ['Monday', 'Wednesday'].

on[days_of_month] Array

Only for month period when on[weekday_of_month] is omitted. An array of days of month numbers (1..28). Please note that 29, 30 and 31 are not supported as not all months have these. E.g.: [1, 15, 20]

on[weekday_of_month] string

Only for month period when on[days_of_month] is omitted. An ordinalized weekday. E.g.: 2nd_monday, last_friday

in_words string

The schedule, in english. E.g.: Every 2 months on the 15th, Every 3 days, Every week on monday and friday

start_date Date

The start date of the schedule in ISO 8601 format

end_date Date

The end date of the schedule in ISO 8601 format

charge Hash

Only in case of charge schedules:

  • amount: The amount to charge at regular interval
  • currency: The currency to be used for said charge
  • description: The description that is applied to all charges created by this schedule.
  • customer: The customer uid to be charged
  • card: The card uid to be charged. Empty in case the default card is charged.

transfer Hash

Only in case of transfer schedules:

  • recipient: The recipient uid to transfer to.
  • amount: The amount to transfer at regular interval. Null if percentage_of_balance is present.
  • currency: The currency to be used for the transfers
  • percentage_of_balance: How many percent of the transferable balance are transfered. Null if amount is present.

occurrences list

A list of occurrence objects.

next_occurrence_dates Array

An array of up to 30 upcoming occurrence dates in ISO 8601 format. Returns an empty array in case of expired, suspended or deleted schedule.

created datetime

Creation date of the schedule in ISO 8601 format.

List all schedules


Returns a list of schedule objects.

Returns all schedules that belongs to your account. You can learn more about lists in the pagination documentation. Please note that this endpoint returns both charge and transfer schedules.


  • List all schedules

Create a schedule


See the specific documentation page for charge schedules.

Retrieve a schedule


Returns an existing schedule object


  • Retrieve a schedule

Destroy a schedule


Destroys and returns an existing schedule object


  • Destroy a schedule