List recipient schedules

GEThttps://api.omise.co/recipients/:id/schedules

List all schedules associated with a specific recipient. Use this endpoint to view recurring transfers and automated payment schedules configured for a recipient.

---

Request Parameters

Required - 1 fieldRequired Parameters

▼

`id`STRING(required)

Recipient ID (e.g., recp_test_...). Provided in the URL path.

Example:"recp_test_5xuy4w91xqz7d1w9u0t"

Optional - 5 fieldsPagination Parameters

▼

`limit`INTEGER(optional)

Number of schedules to return per page.

Example:20

Constraints:Minimum: 1, Maximum: 100

Default:20

`offset`INTEGER(optional)

Number of schedules to skip for pagination.

Example:0

Default:0

`order`STRING(optional)

Sort order of results.

Example:"chronological"

Values:chronological, reverse_chronological

Default:"chronological"

`from`STRING(optional)

Earliest UTC datetime in ISO 8601 format. Returns schedules created on or after this date.

Example:"2025-01-01T00:00:00Z"

`to`STRING(optional)

Latest UTC datetime in ISO 8601 format. Returns schedules created before this date.

Example:"2025-12-31T23:59:59Z"

---

Responses

200

Successful retrieval

Returns a paginated list of schedule objects associated with the recipient. Each schedule contains frequency, status, and transfer details.

Response includes:

• object - Always "list"
• data - Array of schedule objects
• limit - Number of results per page
• offset - Number of skipped results
• total - Total number of schedules for this recipient
• order - Sort order applied

Schedule object fields:

• id - Schedule identifier
• status - active, expired, suspended, deleted, paused
• period - day, week, or month
• every - Frequency multiplier for the period
• next_occurrences_on - Array of upcoming occurrence dates
• transfer - Transfer parameters for this schedule

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Invalid date format for from or to
• Invalid order value
• Negative offset or limit
• limit exceeds maximum (100)

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

Recipient not found.

Common causes:

• Invalid recipient ID
• Recipient does not belong to your account
• Recipient has been deleted
• Mixing test and live mode IDs

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/recipients/recp_test_5xuy4w91xqz7d1w9u0t/schedules \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -G \
  -d limit=20 \
  -d offset=0

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

recipient = Omise::Recipient.retrieve('recp_test_5xuy4w91xqz7d1w9u0t')
schedules = recipient.schedules(limit: 20, offset: 0)

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

recipient = omise.Recipient.retrieve('recp_test_5xuy4w91xqz7d1w9u0t')
schedules = recipient.schedules(limit=20, offset=0)

Node.js

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

const schedules = await omise.recipients.listSchedules(
  'recp_test_5xuy4w91xqz7d1w9u0t',
  { limit: 20, offset: 0 }
);

PHP

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

$recipient = OmiseRecipient::retrieve('recp_test_5xuy4w91xqz7d1w9u0t');
$schedules = $recipient->schedules([
    'limit' => 20,
    'offset' => 0
]);

Java

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

ScopedList<Schedule> schedules = client.recipients()
    .get("recp_test_5xuy4w91xqz7d1w9u0t")
    .schedules()
    .list(new ScopedList.Options()
        .limit(20)
        .offset(0));

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var schedules = await client.Recipients.ListSchedules(
    "recp_test_5xuy4w91xqz7d1w9u0t",
    new ListOptions
    {
        Limit = 20,
        Offset = 0
    }
);

Go

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

schedules, _ := client.Recipients().ListSchedules(
    "recp_test_5xuy4w91xqz7d1w9u0t",
    &operations.ListSchedules{
        List: operations.List{
            Limit:  20,
            Offset: 0,
        },
    },
)

---

Pagination

Use limit and offset parameters to paginate through results:

# First page (0-19)
curl https://api.omise.co/recipients/recp_test_5xuy4w91xqz7d1w9u0t/schedules?limit=20&offset=0 \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

# Second page (20-39)
curl https://api.omise.co/recipients/recp_test_5xuy4w91xqz7d1w9u0t/schedules?limit=20&offset=20 \
  -u skey_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	Recipient not found	Check the recipient ID is correct
bad_request	Invalid parameters	Check date format and parameter values
invalid_date_format	Date not in ISO 8601	Use format: YYYY-MM-DDTHH:MM:SSZ

Schedule Status Values

Status	Description
active	Schedule is running normally
expired	Schedule has passed end date
suspended	Schedule is paused (failures, verification issues)
deleted	Schedule has been cancelled
paused	Schedule manually paused

---

🔑API Credentials

▼

Try it out

Required - 1 fields

▼

id(Required)

Your IP: ...Loading...