Charge Schedule API

Charge schedules are a type of schedules. For more information about schedules, check the schedules documentation

Attribute

Name Type Description
object string

The string schedule.

id object_id

The SCHEDULE_ID.

livemode boolean

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

location string

Path to retrieve the charge 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[amount] integer

The amount to charge at regular interval

charge[currency] string

The currency to be used for said charge.

charge[description] string

The description that is applied to all charges created by this schedule.

charge[customer] string

The customer uid to be charged

charge[card] string

The card uid to be charged. Empty in case the default card is charged.

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.

Example

  • Json Response

List all charge schedules

- GET https://api.omise.co/charges/schedules

Returns a list of schedule objects.\n\nReturns all charge schedules that belong to your account. You can learn more about lists in the pagination documentation. \nPlease note that this endpoint returns only charge schedules. For other types of schedules, check the schedules documentation

Example

  • List all charge schedules

List all charge schedules for a given customer

- GET https://api.omise.co/customers/Customer_ID/schedules

Returns a list of schedule objects. Returns all charge schedules that belong to a given customer.

Example

  • List all charge schedules for a customer.

Retrieve a charge schedule

- GET https://api.omise.co/schedules/SCHEDULE_ID

Create a charge schedule

- POST https://api.omise.co/schedules

Creates and returns a new charge schedule object.

Request Parameter

Name Type Description
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

start_date Date

When the schedule should start, in ISO 8601 format (YYYY-MM-DD). Defaults to today.

end_date Date

When the schedule should end, in ISO 8601 format (YYYY-MM-DD)

charge[amount] integer

integer

charge[currency] string

The currency to be used for said charge.

charge[description] string

The description that is applied to all charges created by this schedule.

charge[customer] string

The customer uid to be charged.

charge[card] string

The card uid to be charged. Empty in case the default card is charged.

Example

  • Charge to a specific customer every 2 days

  • Charge every Monday and Friday

  • Charge on the 1st, 10th and 15th every 3 months

  • Charge on the second Monday every month

Destroy a charge schedule

- DELETE https://api.omise.co/schedules/SCHEDULE_ID