Retrieve an occurrence

GEThttps://api.omise.co/occurrences/:id

Retrieve details about a specific schedule occurrence. Each occurrence represents one execution of a recurring schedule. Use this endpoint to check if a scheduled payment succeeded, investigate failed charges, and track retry information.

---

🔑API Credentials

▼

---

Request Parameters

Required - 1 fieldPath Parameters

▼

`id`STRING(required)

The occurrence ID to retrieve. Occurrence IDs start with occu_ followed by test_ for test mode.

Example:"occu_test_5xuy4w91xqz7d1w9u0t"

---

Responses

200

Successful retrieval

Returns the occurrence object with execution details, status, and result information.

Occurrence object includes:

• id - Occurrence identifier (occu_*)
• schedule - Parent schedule ID
• scheduled_on - Date when occurrence was intended to be processed
• processed_at - When occurrence was actually processed (ISO 8601)
• status - successful, failed, or skipped
• result - ID of created charge or transfer (null if failed/skipped)
• message - Error message if failed, null if successful
• retry_on - Retry date if processing failed

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid secret key
• Using public key instead of secret key
• Incorrect HTTP Basic Auth format

404

Not found

Occurrence not found or does not exist.

Common causes:

• Invalid occurrence ID
• Occurrence ID from different account
• Mixing test and live mode keys

---

Code samples

cURL

curl https://api.omise.co/occurrences/occu_test_5xuy4w91xqz7d1w9u0t \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

occurrence = Omise::Occurrence.retrieve('occu_test_5xuy4w91xqz7d1w9u0t')

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

occurrence = omise.Occurrence.retrieve('occu_test_5xuy4w91xqz7d1w9u0t')

Node.js

const omise = require('omise')({
  secretKey: 'skey_test_5xuy4w91xqz7d1w9u0t'
});

const occurrence = await omise.occurrences.retrieve('occu_test_5xuy4w91xqz7d1w9u0t');

PHP

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');

$occurrence = OmiseOccurrence::retrieve('occu_test_5xuy4w91xqz7d1w9u0t');

Java

Client client = new Client.Builder()
    .secretKey("skey_test_5xuy4w91xqz7d1w9u0t")
    .build();

Occurrence occurrence = client.occurrences().get("occu_test_5xuy4w91xqz7d1w9u0t");

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var occurrence = await client.Occurrences.Get("occu_test_5xuy4w91xqz7d1w9u0t");

Go

client, _ := omise.NewClient(
    "pkey_test_5xuy4w91xqz7d1w9u0t",
    "skey_test_5xuy4w91xqz7d1w9u0t",
)

occurrence, _ := client.GetOccurrence("occu_test_5xuy4w91xqz7d1w9u0t")

---

Error and result codes

Common Error Codes

Code	Description	Resolution
authentication_failure	Invalid API key	Verify your secret key is correct
not_found	Occurrence not found	Check occurrence ID and ensure correct mode (test/live)

Occurrence Status Values

Status	Description
successful	Charge/transfer created successfully
failed	Execution failed (card declined, insufficient funds, etc.)
skipped	Occurrence was skipped (schedule suspended, customer deleted)

Common Failure Messages

Message	Description
insufficient_fund	Customer has insufficient funds
card_declined	Card was declined by issuer
expired_card	Card has expired
customer_not_found	Customer was deleted

---

Try it out

Required - 1 fields

▼

id(Required)