Schedule API

Create, retrieve, and delete schedules. Schedules are charges or transfers that occur at regular intervals, for example, a monthly membership fee or a weekly transfer. Actual schedule dates are accessed via the occurrence API.

Attributes

Name Type Description
object string

The string schedule.

id string

The schedule identifier matching /schd(_test)?_[0-9a-z]+/.

livemode boolean

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

location string

API path to retrieve the current schedule object.

active boolean

Whether schedule is status active or expiring.

charge charge_schedule
created string

UTC datetime of schedule creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

deleted boolean

Whether schedule is deleted.

end_date string

End date of schedule in ISO 8601 format.

ended_at string

Actual end date of schedule in ISO 8601 format.

every integer

How often schedule should run when applied to period. For example, if set to 3 and period is set to week, schedule should run every 3 weeks.

in_words string

Schedule expressed as an English sentence. E.g.: Every 2 months on the 15th, Every 3 days, Every week on monday and friday.

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.

occurrences list

List of occurrence objects.

on object

Object specifying schedule timing.

period string

Period to use for every. One of day, week or month. For example, if set to week and every is set to 3 schedule should run every 3 weeks.

start_date string

Start date of schedule in ISO 8601 format.

state string

Indicates whether the schedule is Active or Paused.

status string

The current status of the schedule. 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.
  • paused: The schedule is paused
  • suspended: The schedule could not be completed and was stopped. Schedules are suspended three (3) days after the charge is unsuccessful as Opn Payments systems will retry three (3) times, one time per day.
.

transfer transfer_schedule

Example

  • JSON Response

Create a schedule

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

Creates and returns a new schedule.

Note: From the Opn Payments dashboard, you can upload data of multiple cards as a batch for multiple schedules to be created automatically.

Request Parameters

Name Type Description
end_date string

(required) End date of schedule in ISO 8601 format.

every integer

(required) How often schedule should run when applied to period. For example, if set to 3 and period is set to week, schedule should run every 3 weeks.

period string

(required, one of: day, week, month) Period to use for every. One of day, week or month. For example, if set to week and every is set to 3 schedule should run every 3 weeks.

start_date string

(required) Start date of schedule in ISO 8601 format.

charge object

(optional, but conditionally required) Charge schedule object. Use when creating a charge schedule.

on object

(optional) Object specifying schedule timing.

transfer object

(optional, but conditionally required) Transfer schedule object. Use when creating a transfer schedule.

Example

  • Charge a specific customer every 2 days

  • Transfer a fixed amount every 2 days

  • Charge on the 1st every 3 months

  • Charge on the second Monday every month

  • Transfer the whole balance on the second Monday every month

  • Transfer the whole balance on the 1st every 3 months

  • Charge every Monday and Friday

  • Transfer a percentage of the balance every Monday and Friday

Destroy a schedule

- DELETE https://api.omise.co/schedules/{id}

Destroys the schedule matching :id.

Example

  • Destroy a schedule

List schedules

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

Returns a list of charge and transfer schedules belonging to your account.

Request Parameters

Name Type Description
from string

(optional, default: 1970-01-01T00:00:00Z) Earliest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

limit integer

(optional, default: 20) Number of records returned.

offset integer

(optional, default: 0) Offset of the first record returned (i.e. how many records to skip from the beginning).

order string

(optional, default: chronological, one of: chronological, reverse_chronological) Order of records returned.

to string

(optional) Latest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

Example

  • List all schedules

List charge schedules for customer

- GET https://api.omise.co/customers/{id}/schedules

Returns a list of schedules belonging to customer matching :id.

Request Parameters

Name Type Description
from string

(optional, default: 1970-01-01T00:00:00Z) Earliest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

limit integer

(optional, default: 20) Number of records returned.

offset integer

(optional, default: 0) Offset of the first record returned (i.e. how many records to skip from the beginning).

order string

(optional, default: chronological, one of: chronological, reverse_chronological) Order of records returned.

to string

(optional) Latest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

Example

  • List all charge schedules for a customer

List transfer schedules for recipient

- GET https://api.omise.co/recipients/{id}/schedules

Returns a list of transfer schedules belonging to recipient matching :id.

Request Parameters

Name Type Description
from string

(optional, default: 1970-01-01T00:00:00Z) Earliest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

limit integer

(optional, default: 20) Number of records returned.

offset integer

(optional, default: 0) Offset of the first record returned (i.e. how many records to skip from the beginning).

order string

(optional, default: chronological, one of: chronological, reverse_chronological) Order of records returned.

to string

(optional) Latest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

Example

  • List all transfer schedules for recipient

Retrieve a schedule

- GET https://api.omise.co/schedules/{id}

Returns the schedule matching :id.

Example

  • Retrieve a schedule

Omise uses cookies to improve your overall site experience and collect information on your visits and browsing behavior. By continuing to browse our website, you agree to our Privacy Policy. Learn more