Charge Schedule

Topics covered on this page

Charge Schedules are a type of schedule that can be created, retrieved, and deleted. To create a Charge Schedule, create a schedule and populate the charge field with the scheduled_charge object.

This document explains the Charge Schedule API functions.

Authorization

The Charge Schedule API requires the secret API key to authenticate calls. Retrieve this key from Settings > Keys on the dashboard and pass it in the Authorization header.

Objects and Endpoints

Object Endpoint
scheduled_charge

The object containing the scheduled charges.

Bulk create scheduled charges

Efficiently create multiple charge schedules with a single request by uploading a CSV file, thereby reducing the number of API calls.

Bulk creation example call

Curl Example:

curl -X POST api.omise.co/schedules/upload \
-u "skey_69xetbas274127vgwuyq" \
-H "Content-Type: multipart/form-data" \
-F "file=@example.csv;content_type=text/csv;filename=example.csv"

Bulk creation parameters

[Required] file
string
The name of the CSV file containing the charge schedules to create.

The format of the CSV file is as follows:

customer_key,customer,card,amount,description,every,period,days_of_month,start_date,end_date
CWM2050182,cust_5v9cnm12qfn23ojqs4m,tokn_5w8x77tgkxpc5e766ve,79000,2362776APRAVSAL,1,month,5,2023-8-30,2028-4-5
CWM2050183,cust_5v9o3vfn4ytkugyx1ni,tokn_5w8x7eegq15dci867s5,54800,2362779FHBKOTIU,1,month,15,2023-8-30,2028-4-5
CWM2050184,cust_5v9nz9n1dfiugd5u5pu,tokn_5w8x7gqu1uupgj0w25k,102950,2362739OIHCMHRY,1,month,25,2023-8-30,2028-4-5
Response on Success
{
    "object": "batch_recurring",
    "status": "pending",
    "id": "recurr_test_607n5qpyv3692z50f5l",
    "livemode": false,
    "created_at": "2024-06-26T06:59:32Z",
    "updated_at": "2024-06-26T06:59:32Z",
    "name": "test-little-john-batch_recurring_report_2024-06-26T06-59-32Z.csv",
    "team": "team_little_john",
    "entries": 3,
    "schedule_created_count": 0,
    "downloadable": false
}

Bulk creation response codes

Code Example
200 - OK See Response on Success
400 - Bad Request
Check whether you have passed the file name correctly, and whether the file exists.		 
{
    "object": "error",
    "location": "https://www.omise.co/api-errors#missing-file",
    "code": "missing_file",
    "message": "missing file or filename"
}
401 - Unauthorized
Check whether the authentication key is valid.		 
{
    "object": "error",
    "location": "https://www.omise.co/api-errors#authentication-failure",
    "code": "authentication_failure",
    "message": "authentication failed"
}

Monitor bulk creation

Processing a file with many records and generating a charge schedule can be time-consuming. To track progress, use the following API call.

Monitor bulk creation example call

Curl Example:

curl -X GET api.omise.co/recurring_exports/recurr_60cc00s55gwhoifwvy5 \
-u "skey_69xetbas274127vgwuyq"

Monitor the batch creation with job ID recurr_60cc00s55gwhoifwvy5.

Monitor bulk creation parameters

[Required] recurring_id string
The ID of the batch creation job to monitor.

 Response on Success
{
    "object": "batch_recurring",
    "status": "successful",
    "id": "recurr_60cc00s55gwhoifwvy5",
    "livemode": true,
    "created_at": "2024-07-08T06:46:27Z",
    "updated_at": "2024-07-08T06:46:27Z",
    "name": "muthuswamy-d-opn-ooo-batch_recurring_report_2024-07-08T06-46-27Z.csv",
    "team": "team_5yv5mcyalnj9keejz9k",
    "entries": 3,
    "schedule_created_count": 0,
    "downloadable": true

Monitor bulk creation response codes

Code Example
200 - OK See Response on Success
401 - Unauthorized
Check whether the authentication key is valid.		 
{
    "object": "error",
    "location": "https://www.omise.co/api-errors#authentication-failure",
    "code": "authentication_failure",
    "message": "authentication failed"
}
404 - Not found
Check whether the job ID is valid,		 
{
    "object": "error",
    "location": "https://www.omise.co/api-errors#not-found",
    "code": "not_found",
    "message": "recurr_test_607n5qpyv3692z50f5l was not found"
}

Download bulk creation status

If errors occur during bulk creation, use the following API call to download the status report and carefully review any errors.

Download bulk creation status example call

Curl Example:

curl -X GET api.omise.co/recurring_exports/recurr_test_607n5qpyv3692z50f5l/download \
-u "skey_69xetbas274127vgwuyq"

Download the status report of the batch creation job with ID recurr_test_607n5qpyv3692z50f5l.

Download bulk creation status parameters

[Required] recurring_id string
The ID of the batch creation job to monitor.

 Response on Success
customer_key,customer,card,amount,description,every,period,days_of_month,start_date,end_date,status,error_message
CWM2050182,cust_5v9cnm12qfn23ojqs4m,tokn_5w8x77tgkxpc5e766ve,79000,2362776APRAVSAL,1,month,5,2023-8-30,2028-4-5,failed,start date must not be in the past
CWM2050183,cust_5v9o3vfn4ytkugyx1ni,tokn_5w8x7eegq15dci867s5,54800,2362779FHBKOTIU,1,month,15,2023-8-30,2028-4-5,failed,start date must not be in the past
CWM2050184,cust_5v9nz9n1dfiugd5u5pu,tokn_5w8x7gqu1uupgj0w25k,102950,2362739OIHCMHRY,1,month,25,2023-8-30,2028-4-5,failed,start date must not be in the past

Download bulk creation status response codes

Code Example
200 - OK See Response on Success
401 - Unauthorized
Check whether the authentication key is valid.		 
{
    "object": "error",
    "location": "https://www.omise.co/api-errors#authentication-failure",
    "code": "authentication_failure",
    "message": "authentication failed"
}
404 - Not found
Check whether the job ID is valid,		 
{
    "object": "error",
    "location": "https://www.omise.co/api-errors#not-found",
    "code": "not_found",
    "message": "recurr_test_607n5qpyv3692z50f5l was not found"
}

List charge schedules

Use the following API to list charge schedules.

List charge schedules example call

Curl Example:

curl -X GET api.omise.co/charges/schedules?limit=1 \
-u "skey_69xetbas274127vgwuyq"

List charge schedules parameters

[Optional] from string
default: 1970-01-01T00:00:00Z
Earliest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

[Optional] limit integer
default: 20
Number of records returned.

[Optional] offset integer
default: 0
Offset of the first record returned (i.e. how many records to skip from the beginning).

[Optional] order string
default: chronological
one of: chronological, reverse_chronological. Order of records returned.

[Optional] to string
Latest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

 Response on Success
{
    "object": "list",
    "data": [
        {
            "object": "schedule",
            "id": "schd_test_60ceqabns9pynevomwi",
            "deleted": false,
            "livemode": false,
            "location": "/schedules/schd_test_60ceqabns9pynevomwi",
            "every": 1,
            "occurrences": {
                "object": "list",
                "data": [],
                "limit": 20,
                "offset": 0,
                "total": 0,
                "location": "/schedules/schd_test_60ceqabns9pynevomwi/occurrences",
                "order": "chronological",
                "from": "1970-01-01T00:00:00Z",
                "to": "2024-07-10T05:02:09Z"
            },
            "on": {
                "days_of_month": [
                    16
                ]
            },
            "in_words": "Every 1 month(s) on the 16th",
            "period": "month",
            "status": "running",
            "active": true,
            "state": "Active",
            "charge": {
                "object": "scheduled_charge",
                "id": "rchg_test_60ceqabn7y94oculsz2",
                "livemode": false,
                "currency": "THB",
                "amount": 400000,
                "default_card": false,
                "card": "card_test_60cenmixr9xykldjl5a",
                "customer": "cust_test_60ceo1saqfzick3wjn3",
                "description": "Test",
                "metadata": {},
                "created_at": "2024-07-08T11:25:36Z"
            },
            "next_occurrences_on": [
                "2024-07-16",
                "2024-08-16",
                "2024-09-16",
                "2024-10-16",
                "2024-11-16",
                "2024-12-16",
                "2025-01-16",
                "2025-02-16",
                "2025-03-16",
                "2025-04-16",
                "2025-05-16",
                "2025-06-16"
            ],
            "ended_at": null,
            "start_on": "2024-07-08",
            "end_on": "2025-07-08",
            "created_at": "2024-07-08T11:25:36Z"
        }
    ],
    "limit": 1,
    "offset": 0,
    "total": 2,
    "location": "/charges/schedules",
    "order": "chronological",
    "from": "1970-01-01T00:00:00Z",
    "to": "2024-07-10T05:02:09Z"
}

List charge schedules response codes

Code Example
200 - OK See Response on Success
401 - Unauthorized
Check whether the authentication key is valid.		 
{
    "object": "error",
    "location": "https://www.omise.co/api-errors#authentication-failure",
    "code": "authentication_failure",
    "message": "authentication failed"
}

Pause charge schedules

Use the following API to pause charge schedules.

Pause charge schedules example call

Curl Example:

curl -X PATCH api.omise.co//schedules/bulk_pause \
-u "skey_69xetbas274127vgwuyq" \
-H "Accept: application/json" \
-d "schedule_ids:{schd_test_5zp4k5qd17me1agpo7t,schd_test_67gwqtwbd17me1agpgwf}"

Pause the charge schedules with IDs schd_test_5zp4k5qd17me1agpo7t and schd_test_67gwqtwbd17me1agpgwf.

Pause charge schedules parameters

[Required] schedule_ids array of string
The IDs of one or more charge schedules to pause.

 Response on Success
{
    "object": "bulk",
    "updated_count": 1,
    "failed_count": 0,
    "success_schedule_ids": [
        "schd_test_5zp4k5qd17me1agpo7t",
        "schd_test_67gwqtwbd17me1agpgwf"
    ]
}

Pause charge schedule response codes

Code Example
200 - OK [Success] See Response on Success
200 - OK [Failure]
Check whether you have passed a schedule ID and it exists.		 
{
    "object": "bulk",
    "updated_count": 0,
    "failed_count": 1,
    "failed_schedule_ids": [
        "schd_test_5zp4k5qd17me1agpo7t"
    ]
}
401 - Unauthorized
Check whether the authentication key is valid.		 
{
    "object": "error",
    "location": "https://www.omise.co/api-errors#authentication-failure",
    "code": "authentication_failure",
    "message": "authentication failed"
}

Resume charge schedules

Use the following API to resume charge schedules.

Resume charge schedules example call

Curl Example:

curl -X PATCH api.omise.co//schedules/bulk_resume \
-u "skey_69xetbas274127vgwuyq" \
-H "Accept: application/json" \
-d "schedule_ids:{schd_test_5zp4k5qd17me1agpo7t,schd_test_67gwqtwbd17me1agpgwf}"

Resume the charge schedules with IDs schd_test_5zp4k5qd17me1agpo7t and schd_test_67gwqtwbd17me1agpgwf.

Resume charge schedules parameters

[Required] schedule_ids array of string
The IDs of one or more charge schedules to resume.

 Response on Success
{
    "object": "bulk",
    "updated_count": 1,
    "failed_count": 0,
    "success_schedule_ids": [
        "schd_test_5zp4k5qd17me1agpo7t",
        "schd_test_67gwqtwbd17me1agpgwf"
    ]
}

Resume charge schedule response codes

Code Example
200 - OK See Response on Success
200 - OK [Failure]
Check whether you have passed a schedule ID and it exists.		 
{
    "object": "bulk",
    "updated_count": 0,
    "failed_count": 1,
    "failed_schedule_ids": [
        "schd_test_5zp4k5qd17me1agpo7t"
    ]
}
401 - Unauthorized
Check whether the authentication key is valid.		 
{
    "object": "error",
    "location": "https://www.omise.co/api-errors#authentication-failure",
    "code": "authentication_failure",
    "message": "authentication failed"
}

Delete charge schedules

Use the following API to delete charge schedules.

Delete charge schedules example call

Curl Example:

curl -X DELETE api.omise.co//schedules/bulk_delete \
-u "skey_69xetbas274127vgwuyq" \
-H "Accept: application/json" \
-d "schedule_ids:{schd_test_5zp4k5qd17me1agpo7t}"

Delete the charge schedule with IDs schd_test_5zp4k5qd17me1agpo7t.

Delete charge schedules parameters

[Required] schedule_ids array of string
The IDs of one or more charge schedules to delete.

 Response on Success
{
    "object": "bulk",
    "updated_count": 1,
    "failed_count": 0,
    "success_schedule_ids": [
        "schd_test_5zp4k5qd17me1agpo7t"
    ]
}

Delete charge schedule response codes

Code Example
200 - OK See Response on Success
401 - Unauthorized
Check whether the authentication key is valid.		 
{
    "object": "error",
    "location": "https://www.omise.co/api-errors#authentication-failure",
    "code": "authentication_failure",
    "message": "authentication failed"
}
404 - Not found
Check whether you have passed a valid schedule ID.		 
{
    "object": "error",
    "location": "https://www.omise.co/api-errors#not-found",
    "code": "not_found",
    "message": "schedule schd_test_60ceqabns9pynevomwt was not found"
}
Omise uses cookies to improve your overall site experience and collect information on your visits and browsing behavior. By continuing to browse our website, you agree to our Privacy Policy. Learn more