Occurrence API

The Occurrence API allows you to retrieve "occurrences", or actual execution dates, for a given charge or transfer schedule. Queryable information includes the retry date, status, or result of a given occurrence.


Name Type Description
object string

The string occurrence.

id object_id

The OCCURRENCE_ID matching /occu(_test)?_[1-9a-z]+/.

livemode boolean

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

location string

API path to retrieve the current occurrence object.

created datetime

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

message string

If the occurrence processing had some issue, this will provide an error message, a warning, or an explanation regarding the status.

processed_at datetime

The UTC datetime at which the occurrence was processed (regardless of success or failure) in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

result object_id

The object or the reference to the object that was created as a result of processing the occurrence: either a CHARGE_ID, TRANSFER_ID, or their respective objects. Empty in case the object could not be created. In that case, message will give you more information.

retry_date Date

If the occurrence failed on its schedule_date (e.g.: due to the bank rejecting the charge), a duplicate occurrence is created and is processed on retry_date (the next day). Empty if the occurrence was processed successfuly on its schedule_date.

schedule object_id

The SCHEDULE_ID or schedule object to which this occurrence belongs.

schedule_date Date

The date on which the occurrence was intended to be processed in ISO 8601 format (YYYY-MM-DD).

status string

Status of the scheduled occurrence. One of skipped, failed or successful.

List all occurrences for a given schedule

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

Returns a list of all occurrence objects belonging to the schedule.

Request Parameter

Name Type Description
offset integer

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

limit integer

(optional, default: 20, maximum: 100) The number of records returned.

from datetime

(optional, default: 1970-01-01T00:00:00Z) The earliest UTC date and time for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

to datetime

(optional, default: current UTC datetime) The latest UTC date and time for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

order string

(optional, default: chronological) The order of the list returned. Either chronological (earliest to latest) or reverse_chronological (latest to earliest).


  • List occurrences

Retrieve an occurrence

- GET https://api.omise.co/occurrences/OCCURRENCE_ID

Returns an existing occurrence object


  • Retrieve an occurrence