Monitor bulk creation progress

GEThttps://api.omise.co/recurring_exports/:recurring_id

Retrieve the current status of a bulk charge schedule creation job. Use this endpoint to track progress, check completion status, and determine when the status report is ready for download.

Request Parameters

Required - 1 fieldPath Parameters

▼

`recurring_id`STRING(required)

The recurring export ID returned from the bulk create endpoint. IDs start with recr_.

Example:"recr_test_5xuy4w91xqz7d1w9u0t"

---

Responses

200

Job status retrieved

Returns the current status of the bulk creation job with progress details.

Response includes:

• object - Always "recurring_export"
• id - Recurring export ID (recr_*)
• livemode - Whether this is a live mode operation
• location - API path to this resource
• state - Current job state (pending, processing, completed, failed)
• total_rows - Total number of rows in the CSV
• processed_rows - Number of rows processed so far
• successful_rows - Number of schedules created successfully
• failed_rows - Number of rows that failed to create
• progress_percentage - Completion percentage (0-100)
• download_uri - URI to download status report (available when completed)
• created_at - Job creation timestamp
• completed_at - Job completion timestamp (null if not completed)

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Invalid recurring_id format
• Missing recurring_id parameter

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

Bulk creation job not found.

Common causes:

• Invalid recurring_id
• Job belongs to different account
• Mixing test and live mode keys
• Job has expired (older than 30 days)

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

# Check bulk creation job status
curl https://api.omise.co/recurring_exports/recr_test_5xuy4w91xqz7d1w9u0t \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

Ruby

require 'omise'
require 'net/http'
require 'uri'
require 'json'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

recurring_id = 'recr_test_5xuy4w91xqz7d1w9u0t'

uri = URI("https://api.omise.co/recurring_exports/#{recurring_id}")
request = Net::HTTP::Get.new(uri)
request.basic_auth(Omise.api_key, '')

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

result = JSON.parse(response.body)
puts "State: #{result['state']}"
puts "Progress: #{result['progress_percentage']}%"
puts "Successful: #{result['successful_rows']} / #{result['total_rows']}"

Python

import omise
import requests

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

recurring_id = 'recr_test_5xuy4w91xqz7d1w9u0t'

response = requests.get(
    f'https://api.omise.co/recurring_exports/{recurring_id}',
    auth=(omise.api_secret, '')
)

result = response.json()
print(f"State: {result['state']}")
print(f"Progress: {result['progress_percentage']}%")
print(f"Successful: {result['successful_rows']} / {result['total_rows']}")

Node.js

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

const recurringId = 'recr_test_5xuy4w91xqz7d1w9u0t';

const response = await axios.get(
  `https://api.omise.co/recurring_exports/${recurringId}`,
  {
    auth: {
      username: 'skey_test_5xuy4w91xqz7d1w9u0t',
      password: ''
    }
  }
);

console.log('State:', response.data.state);
console.log('Progress:', response.data.progress_percentage + '%');
console.log('Successful:', response.data.successful_rows, '/', response.data.total_rows);

PHP

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

$recurring_id = 'recr_test_5xuy4w91xqz7d1w9u0t';

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.omise.co/recurring_exports/{$recurring_id}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => OMISE_SECRET_KEY . ':'
]);

$response = curl_exec($curl);
curl_close($curl);

$result = json_decode($response, true);
echo "State: " . $result['state'] . "\n";
echo "Progress: " . $result['progress_percentage'] . "%\n";
echo "Successful: " . $result['successful_rows'] . " / " . $result['total_rows'] . "\n";

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

HttpClient client = HttpClient.newHttpClient();

String recurringId = "recr_test_5xuy4w91xqz7d1w9u0t";
String auth = Base64.getEncoder().encodeToString("skey_test_5xuy4w91xqz7d1w9u0t:".getBytes());

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.omise.co/recurring_exports/" + recurringId))
    .header("Authorization", "Basic " + auth)
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

C#

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();

var credentials = Convert.ToBase64String(
    System.Text.Encoding.ASCII.GetBytes("skey_test_5xuy4w91xqz7d1w9u0t:")
);
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Basic", credentials);

var recurringId = "recr_test_5xuy4w91xqz7d1w9u0t";
var response = await client.GetAsync($"https://api.omise.co/recurring_exports/{recurringId}");
var result = await response.Content.ReadAsStringAsync();

Console.WriteLine(result);

Go

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    recurringId := "recr_test_5xuy4w91xqz7d1w9u0t"

    req, _ := http.NewRequest("GET",
        "https://api.omise.co/recurring_exports/"+recurringId, nil)
    req.SetBasicAuth("skey_test_5xuy4w91xqz7d1w9u0t", "")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)

    fmt.Printf("State: %s\n", result["state"])
    fmt.Printf("Progress: %.0f%%\n", result["progress_percentage"])
}

---

Polling for Completion

Here's an example of polling the endpoint until the job completes:

Node.js

const axios = require('axios');

async function waitForCompletion(recurringId, maxAttempts = 60, intervalMs = 5000) {
  for (let i = 0; i < maxAttempts; i++) {
    const response = await axios.get(
      `https://api.omise.co/recurring_exports/${recurringId}`,
      {
        auth: { username: 'skey_test_5xuy4w91xqz7d1w9u0t', password: '' }
      }
    );

    const { state, progress_percentage, successful_rows, failed_rows, total_rows } = response.data;

    console.log(`Progress: ${progress_percentage}% (${successful_rows + failed_rows}/${total_rows})`);

    if (state === 'completed') {
      console.log(`Completed! Success: ${successful_rows}, Failed: ${failed_rows}`);
      return response.data;
    }

    if (state === 'failed') {
      throw new Error('Bulk creation job failed');
    }

    await new Promise(resolve => setTimeout(resolve, intervalMs));
  }

  throw new Error('Timeout waiting for job completion');
}

// Usage
const result = await waitForCompletion('recr_test_5xuy4w91xqz7d1w9u0t');

Python

import time
import requests

def wait_for_completion(recurring_id, max_attempts=60, interval_sec=5):
    api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

    for _ in range(max_attempts):
        response = requests.get(
            f'https://api.omise.co/recurring_exports/{recurring_id}',
            auth=(api_secret, '')
        )
        result = response.json()

        state = result['state']
        progress = result['progress_percentage']
        successful = result['successful_rows']
        failed = result['failed_rows']
        total = result['total_rows']

        print(f"Progress: {progress}% ({successful + failed}/{total})")

        if state == 'completed':
            print(f"Completed! Success: {successful}, Failed: {failed}")
            return result

        if state == 'failed':
            raise Exception('Bulk creation job failed')

        time.sleep(interval_sec)

    raise Exception('Timeout waiting for job completion')

# Usage
result = wait_for_completion('recr_test_5xuy4w91xqz7d1w9u0t')

---

Error and result codes

Job States

State	Description	Next Steps
pending	Job is queued	Wait and poll again
processing	Job is actively running	Wait and poll again
completed	Job finished	Download status report
failed	Job encountered fatal error	Check error message, retry upload

Common Error Codes

Code	Description	Resolution
authentication_failure	Invalid API key	Verify your secret key is correct
not_found	Job not found	Check recurring_id is correct
job_expired	Job data expired	Jobs are retained for 30 days

---

🔑API Credentials

▼

Try it out

Required - 1 fields

▼

recurring_id(Required)

Your IP: ...Loading...