Create a schedule

POSThttps://api.omise.co/schedules

Create a new recurring schedule for automated charges or transfers. Schedules allow you to set up subscription billing, recurring payments, and automated fund transfers with flexible frequency options (daily, weekly, or monthly).

---

Request Parameters

Required - 3 fieldsSchedule Configuration

▼

`every`INTEGER(required)

Frequency multiplier for the schedule period. For example, every=2 with period=week means every 2 weeks.

Example:1

Constraints:Minimum: 1

`period`STRING(required)

Time unit for the schedule frequency.

Example:"month"

Values:day, week, month

`on`OBJECT(required)

Specifies when during the period the schedule should run. Required fields depend on the period type.

Example:"{\"days_of_month\": [1, 15]}"

Optional - 2 fieldsSchedule Duration

▼

`start_date`STRING(optional)

Start date for the schedule in ISO 8601 format (YYYY-MM-DD). Defaults to today if not specified.

Example:"2025-01-01"

`end_date`STRING(optional)

End date for the schedule in ISO 8601 format (YYYY-MM-DD). Schedule will expire after this date.

Example:"2025-12-31"

Conditional - Use charge OR transferCharge Configuration

▼

`charge`OBJECT(optional)

Configuration for recurring charges. Required if not using transfer.

Example:"{\"amount\": 100000, \"currency\": \"THB\", \"customer\": \"cust_test_xxx\"}"

Conditional - Use charge OR transferTransfer Configuration

▼

---

Responses

200

Schedule created

Returns the newly created schedule object with all configuration details and upcoming occurrence dates.

Schedule object includes:

• id - Schedule identifier (schd_*)
• livemode - Live or test mode
• location - API path to object
• status - Initial status (typically "active")
• active - Whether schedule is currently running
• every - Frequency multiplier
• period - Time unit (day, week, month)
• on - Timing configuration
• in_words - Human-readable description of the schedule
• start_on - Schedule start date
• end_on - Schedule end date
• next_occurrences_on - Array of up to 30 upcoming execution dates
• occurrences - List of occurrence objects
• charge or transfer - Operation parameters
• created_at - Schedule creation timestamp (ISO 8601)
• deleted - Whether schedule has been deleted

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Missing required parameters (every, period, on)
• Invalid period value
• Invalid on configuration for the specified period
• Neither charge nor transfer specified
• Invalid customer or recipient ID
• Start date is in the past
• End date is before start date

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

Referenced resource not found.

Common causes:

• Invalid customer ID in charge configuration
• Invalid recipient ID in transfer configuration
• Invalid card ID specified
• Customer has no default card

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

Create a Charge Schedule

cURL

# Monthly charge schedule on the 1st and 15th
curl https://api.omise.co/schedules \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -d every=1 \
  -d period=month \
  -d "on[days_of_month][]=1" \
  -d "on[days_of_month][]=15" \
  -d start_date=2025-01-01 \
  -d end_date=2025-12-31 \
  -d "charge[amount]=100000" \
  -d "charge[currency]=THB" \
  -d "charge[customer]=cust_test_5xuy4w91xqz7d1w9u0t" \
  -d "charge[description]=Monthly subscription"

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

schedule = Omise::Schedule.create({
  every: 1,
  period: 'month',
  on: {
    days_of_month: [1, 15]
  },
  start_date: '2025-01-01',
  end_date: '2025-12-31',
  charge: {
    amount: 100000,
    currency: 'THB',
    customer: 'cust_test_5xuy4w91xqz7d1w9u0t',
    description: 'Monthly subscription'
  }
})

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

schedule = omise.Schedule.create(
    every=1,
    period='month',
    on={
        'days_of_month': [1, 15]
    },
    start_date='2025-01-01',
    end_date='2025-12-31',
    charge={
        'amount': 100000,
        'currency': 'THB',
        'customer': 'cust_test_5xuy4w91xqz7d1w9u0t',
        'description': 'Monthly subscription'
    }
)

Node.js

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

const schedule = await omise.schedules.create({
  every: 1,
  period: 'month',
  on: {
    days_of_month: [1, 15]
  },
  start_date: '2025-01-01',
  end_date: '2025-12-31',
  charge: {
    amount: 100000,
    currency: 'THB',
    customer: 'cust_test_5xuy4w91xqz7d1w9u0t',
    description: 'Monthly subscription'
  }
});

PHP

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

$schedule = OmiseSchedule::create(array(
    'every' => 1,
    'period' => 'month',
    'on' => array(
        'days_of_month' => array(1, 15)
    ),
    'start_date' => '2025-01-01',
    'end_date' => '2025-12-31',
    'charge' => array(
        'amount' => 100000,
        'currency' => 'THB',
        'customer' => 'cust_test_5xuy4w91xqz7d1w9u0t',
        'description' => 'Monthly subscription'
    )
));

Java

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

Schedule schedule = client.schedules().create(new Schedule.CreateParams.Builder()
    .every(1)
    .period(Period.MONTH)
    .on(new Schedule.On.Builder()
        .daysOfMonth(Arrays.asList(1, 15))
        .build())
    .startDate("2025-01-01")
    .endDate("2025-12-31")
    .charge(new Schedule.ChargeParams.Builder()
        .amount(100000)
        .currency("THB")
        .customer("cust_test_5xuy4w91xqz7d1w9u0t")
        .description("Monthly subscription")
        .build())
    .build());

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var schedule = await client.Schedules.Create(new CreateScheduleRequest
{
    Every = 1,
    Period = Period.Month,
    On = new ScheduleOn
    {
        DaysOfMonth = new[] { 1, 15 }
    },
    StartDate = "2025-01-01",
    EndDate = "2025-12-31",
    Charge = new ChargeScheduleParams
    {
        Amount = 100000,
        Currency = "THB",
        Customer = "cust_test_5xuy4w91xqz7d1w9u0t",
        Description = "Monthly subscription"
    }
});

Go

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

schedule, _ := client.CreateSchedule(&operations.CreateSchedule{
    Every:     1,
    Period:    "month",
    On: operations.ScheduleOn{
        DaysOfMonth: []int{1, 15},
    },
    StartDate: "2025-01-01",
    EndDate:   "2025-12-31",
    Charge: &operations.ChargeSchedule{
        Amount:      100000,
        Currency:    "THB",
        Customer:    "cust_test_5xuy4w91xqz7d1w9u0t",
        Description: "Monthly subscription",
    },
})

Create a Transfer Schedule

cURL

# Weekly transfer schedule - every Monday, 75% of balance
curl https://api.omise.co/schedules \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -d every=1 \
  -d period=week \
  -d "on[weekdays][]=monday" \
  -d start_date=2025-01-01 \
  -d end_date=2025-12-31 \
  -d "transfer[recipient]=recp_test_5xuy4w91xqz7d1w9u0t" \
  -d "transfer[percentage_of_balance]=75"

# Monthly fixed amount transfer on the 1st
curl https://api.omise.co/schedules \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -d every=1 \
  -d period=month \
  -d "on[days_of_month][]=1" \
  -d start_date=2025-01-01 \
  -d "transfer[recipient]=recp_test_5xuy4w91xqz7d1w9u0t" \
  -d "transfer[amount]=1000000"

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

# Transfer 75% of balance every Monday
schedule = Omise::Schedule.create({
  every: 1,
  period: 'week',
  on: {
    weekdays: ['monday']
  },
  start_date: '2025-01-01',
  end_date: '2025-12-31',
  transfer: {
    recipient: 'recp_test_5xuy4w91xqz7d1w9u0t',
    percentage_of_balance: 75
  }
})

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

# Transfer 75% of balance every Monday
schedule = omise.Schedule.create(
    every=1,
    period='week',
    on={
        'weekdays': ['monday']
    },
    start_date='2025-01-01',
    end_date='2025-12-31',
    transfer={
        'recipient': 'recp_test_5xuy4w91xqz7d1w9u0t',
        'percentage_of_balance': 75
    }
)

Node.js

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

// Transfer 75% of balance every Monday
const schedule = await omise.schedules.create({
  every: 1,
  period: 'week',
  on: {
    weekdays: ['monday']
  },
  start_date: '2025-01-01',
  end_date: '2025-12-31',
  transfer: {
    recipient: 'recp_test_5xuy4w91xqz7d1w9u0t',
    percentage_of_balance: 75
  }
});

PHP

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

// Transfer 75% of balance every Monday
$schedule = OmiseSchedule::create(array(
    'every' => 1,
    'period' => 'week',
    'on' => array(
        'weekdays' => array('monday')
    ),
    'start_date' => '2025-01-01',
    'end_date' => '2025-12-31',
    'transfer' => array(
        'recipient' => 'recp_test_5xuy4w91xqz7d1w9u0t',
        'percentage_of_balance' => 75
    )
));

Go

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

// Transfer 75% of balance every Monday
schedule, _ := client.CreateSchedule(&operations.CreateSchedule{
    Every:     1,
    Period:    "week",
    On: operations.ScheduleOn{
        Weekdays: []string{"monday"},
    },
    StartDate: "2025-01-01",
    EndDate:   "2025-12-31",
    Transfer: &operations.TransferSchedule{
        Recipient:           "recp_test_5xuy4w91xqz7d1w9u0t",
        PercentageOfBalance: 75,
    },
})

---

Error and result codes

Common Error Codes

Code	Description	Resolution
authentication_failure	Invalid API key	Verify your secret key is correct
invalid_schedule	Invalid schedule configuration	Check every, period, and on parameters
invalid_customer	Customer not found	Verify customer ID exists
invalid_recipient	Recipient not found	Verify recipient ID exists
invalid_card	Card not found or expired	Verify card ID or use customer default

Schedule Period Configuration

Period	Required on Parameter	Example
day	None required	Runs every N days
week	weekdays	{"weekdays": ["monday", "friday"]}
month	days_of_month or weekday_of_month	{"days_of_month": [1, 15]}

---

🔑API Credentials

▼

Try it out

Required - 3 fields

▼

every(Required)

period(Required)

on[days_of_month][](Optional)

Your IP: ...Loading...