Charge Schedule

The Schedule API allows you to create, retrieve, and delete Charge Schedules, a type of schedule. To create a new Charge Schedule, create a new schedule and populate the charge field with this object.

Note: use of this API is disabled for 3DS-enabled accounts.

Attributes

Name Type Description
object string

The string scheduled_charge.

id object_id

The scheduled charge identifier matching /rchg(_test)?_[0-9a-z]+/.

livemode boolean

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

amount integer

Amount for scheduled charge in smallest currency unit.

card object_id

Identifier for card to be charged.

created_at datetime

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

currency currency

Currency for scheduled charge as three-letter ISO 4217 code.

customer object_id

Identifier for customer to be charged.

default_card boolean

Whether card is default card of customer.

description string

Scheduled charge description.

Example

  • JSON Response

Create a charge schedule

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

Creates and returns a new charge schedule. Note: this endpoint is not available for 3DS-enabled accounts. If you have a 3DS-enabled account, please create a new account to use this feature.

Request Parameters

Name Type Description
charge[amount] integer

(required) Amount for scheduled charge in smallest currency unit.

charge[customer] object_id

(required) Identifier for customer to be charged.

end_on date

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

on[days_of_month] array

(optional, but conditionally required) Required when on[period]=month and 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

(optional, but conditionally required) Required when on[period]=month and when on[days_of_month] is omitted. An ordinalized weekday. E.g.: 2nd_monday, last_friday.

on[weekdays] array

(optional, but conditionally required) Required when on[period]=week. An array of weekday names. E.g.: ['Monday', 'Wednesday'].

charge[card] object_id

(optional) CARD_ID for charge schedule. If empty, default card of customer will be used.

charge[currency] currency

(optional) Currency for scheduled charge as three-letter ISO 4217 code.

charge[description] string

(optional) Scheduled charge description.

start_on date

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

Example

  • Charge 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

Retrieve a charge schedule

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

See schedules documentation for more information.

Destroy a charge schedule

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

See schedules documentation for more information.

List charge schedules

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

Returns a list of charge schedules belonging to your account.

Request Parameters

Name Type Description
from datetime

(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, maximum: 100) 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) Order of records returned. One of chronological (earliest to latest) or reverse_chronological (latest to earliest).

to datetime

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

Example

  • List all charge schedules

List charge schedules for a customer

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

Returns a list of schedules that belong to a customer.

Request Parameters

Name Type Description
from datetime

(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, maximum: 100) 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) Order of records returned. One of chronological (earliest to latest) or reverse_chronological (latest to earliest).

to datetime

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

Example

  • List all charge schedules for a customer