Occurrence API

Occurrences are objects that represent actual schedule dates. For example, if you had a schedule set to charge your customer every 1st Monday of each month for 3 months from January 1, 2017, your occurrences would be:

  • Monday, January 2, 2017
  • Monday, February 6, 2017
  • Monday, March 6, 2017

Sometimes, occurrences are not successful. For example, the charge your occurrence was supposed to create could be rejected by the bank. When that happens, a duplicate occurrence gets created to be retried on the next day. E.g.:

  • Monday, January 2, 2017 - Successful
  • Monday, February 6, 2017 - Failed
  • Tuesday, February 7, 2017 - Successful retry
  • Monday, March 6, 2017 - Successful

After 3 consecutive failures, the schedule gets suspended:

  • Monday, January 2, 2017 - Successful
  • Monday, February 6, 2017 - Failed
  • Tuesday, February 7, 2017 - Failed retry
  • Wednesday, February 8, 2017 - Failed retry
  • Schedule suspended.

Attribute

Name Type Description
object string

The string occurrence.

id object_id

The OCCURRENCE_ID.

livemode boolean

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

location string

Path to retrieve the occurrence.

schedule string

The SCHEDULE_ID this occurrence belongs to (expandable).

schedule_date Date

The date on which the occurrence was supposed to be processed. ISO 8601 format.

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. ISO 8601 format.

processed_at datetime

The date and time at which the occurrence was processed (regardless of success or failure). ISO 8601 format.

status string

Either skipped, failed or successful

message string

If the occurrence processing didn't go according to plan, the message will give you information as to how to fix that. It could be an error message, a warning of explanations regarding the status.

result Object

Either a CHARGE_ID or a TRANSFER_ID (both expandable). The reference of the object that was created as a result of processing the occurrence. Empty in case the object could not be created. In that case, message will give you more information.

created datetime

Creation date of the occurrence in ISO 8601 format.

List all occurrences for a given schedule

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

Returns a list of occurrence objects that belong to the given schedule. You can learn more about lists in the pagination documentation.

Example

  • List occurrences

Retrieve an occurrence

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

Returns an existing occurrence object

Example

  • Retrieve an occurrence