List Customer Schedules

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

List all schedules associated with a specific customer. This endpoint retrieves recurring charges, subscriptions, and automated payment schedules linked to the customer.

---

Request Parameters

Required - 1 fieldPath Parameters

▼

`id`STRING(required)

The customer ID to retrieve schedules for (must start with cust_).

Example:"cust_test_5xuy4w91xqz7d1w9u0t"

Constraints:Must be a valid customer ID

Optional - 3 fieldsPagination Parameters

▼

`limit`INTEGER(optional)

Number of schedules to return per page.

Example:20

Constraints:Minimum: 1, Maximum: 100, Default: 20

Default:20

`offset`INTEGER(optional)

Number of schedules to skip for pagination. Use with limit to paginate through large result sets.

Example:0

Default:0

`order`STRING(optional)

Sort order of results.

Example:"chronological"

Values:chronological, reverse_chronological

Default:"chronological"

Optional - 2 fieldsFilter Parameters

▼

---

Responses

200

Successful retrieval

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

Response includes:

• object - Object type (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 customer
• order - Sort order applied

Schedule object fields:

• id - Schedule ID (schd_*)
• status - active, expired, suspended, deleted, paused
• period - day, week, or month
• every - Frequency multiplier for the period
• next_occurrences_on - Array of up to 30 upcoming occurrence dates
• charge or transfer - Operation parameters

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Invalid date format (must be ISO 8601)
• Limit exceeds maximum (100)
• Invalid order parameter
• Negative offset value

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

Customer ID not found.

Common causes:

• Customer ID does not exist
• Customer has been deleted
• Incorrect customer ID format

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

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

customer = Omise::Customer.retrieve('cust_test_5xuy4w91xqz7d1w9u0t')
schedules = customer.schedules({
  limit: 20,
  offset: 0
})

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

customer = omise.Customer.retrieve('cust_test_5xuy4w91xqz7d1w9u0t')
schedules = customer.schedules(
    limit=20,
    offset=0
)

Node.js

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

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

PHP

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

$customer = OmiseCustomer::retrieve('cust_test_5xuy4w91xqz7d1w9u0t');
$schedules = $customer->schedules(array(
    'limit' => 20,
    'offset' => 0
));

Java

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

ScopedList<Schedule> schedules = client.customers()
    .get("cust_test_5xuy4w91xqz7d1w9u0t")
    .schedules()
    .limit(20)
    .offset(0)
    .send();

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var schedules = await client.Customers.ListSchedules("cust_test_5xuy4w91xqz7d1w9u0t", new ListRequest
{
    Limit = 20,
    Offset = 0
});

Go

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

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

---

Error and result codes

Common Error Codes

Code	Description	Resolution
authentication_failure	Invalid API key	Verify your secret key is correct
not_found	Customer not found	Verify customer ID exists
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, card expiry)
deleted	Schedule has been cancelled
paused	Schedule manually paused

List Response Fields

Field	Description
object	Object type (always "list")
data	Array of schedule objects
limit	Number of items per page
offset	Number of items skipped
total	Total number of schedules for this customer
order	Sort order applied
from	Start date filter (if applied)
to	End date filter (if applied)

---

🔑API Credentials

▼

Try it out

Required - 1 fields

▼

id(Required)

Your IP: ...Loading...