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.

---

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:

• object - The value "occurrence"
• id - Occurrence identifier (occu_*)
• livemode - Live or test mode
• location - API path to the occurrence object
• message - Explanation for failure if processing failed
• processed_at - UTC datetime of occurrence processing (ISO 8601)
• result - Result of occurrence processing (charge or transfer ID)
• retry_on - Retry date if processing failed (ISO 8601 date)
• schedule - Schedule to which the occurrence belongs (expandable)
• scheduled_on - Date on which occurrence was scheduled (ISO 8601 date)
• status - Status of occurrence: skipped, failed, or successful
• created_at - Occurrence creation timestamp (ISO 8601)

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

5xx

Server error

Server-side error occurred. These are rare but should be handled gracefully.

How to handle:

• Retry the request with exponential backoff
• Check status.omise.co for service incidents
• See Error Handling for detailed guidance

---

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

Occurrence Object Fields

Field	Type	Description
object	string	Always returns "occurrence"
id	string	Occurrence identifier (occu_*)
livemode	boolean	Live or test mode
location	string	API path to the occurrence object
message	string	Explanation for failure if processing failed
processed_at	datetime	UTC datetime of occurrence processing (ISO 8601)
result	string	Result of occurrence processing (charge or transfer ID)
retry_on	date	Retry date if processing failed (ISO 8601 date)
schedule	string	Schedule to which the occurrence belongs (expandable)
scheduled_on	date	Date on which occurrence was scheduled (ISO 8601 date)
status	string	Status of occurrence: skipped, failed, or successful
created_at	datetime	Occurrence creation timestamp (ISO 8601)

---

🔑API Credentials

▼

Try it out

Required - 1 fields

▼

id(Required)

Your IP: ...Loading...