Charge Schedule

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

Scheduled charge amount in smallest unit of charge currency.

card object_id

Identifier for card to be charged. If a card was not specified at charge schedule creation, this is the customer's current default card.

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.

metadata object

Custom metadata (e.g. {"answer": 42}) for charge schedule.

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) Scheduled charge amount in smallest unit of charge currency.

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 identifier 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.

charge[metadata] object

(optional) Custom metadata (e.g. {"answer": 42}) for charge schedule.

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

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