API reference
Create, list and delete theme schedules for your store over HTTPS. Requests and responses are JSON.
Base URL
https://app.getthemescheduler.com/api/public/schedules
One endpoint with three methods: GET, POST and DELETE. Send request bodies with Content-Type: application/json.
Authentication
Every request needs your store's API key in the Authorization header, either on its own or after Bearer:
Authorization: Bearer YOUR_API_KEY
Authorization: YOUR_API_KEY
Generate the key in the app, in the API Key section (see your API key). A key only works for its own store: the shop you send must match it. Rotating the key in the app turns the old one off right away.
The API allows cross-origin requests, but keep the key out of browser code. Call it from a server or a script.
GET List schedules
Returns every schedule for the store: scheduled, complete and failed.
| Query parameter | Description |
|---|---|
shop, required | Your store's .myshopify.com domain, without https:// |
curl "https://app.getthemescheduler.com/api/public/schedules?shop=your-store.myshopify.com" \
-H "Authorization: Bearer $THEME_SCHEDULER_API_KEY"
Response 200:
{
"schedules": [
{
"id": "6f1c2a40-8d2e-11f1-9a3b-5b1f0c2d7e11",
"shop": "your-store.myshopify.com",
"themeId": "130912345678",
"themeName": "Black Friday",
"publishDate": "2026-11-27",
"publishTime": "00:00",
"timezoneValue": "America/New_York",
"ISOString": "2026-11-27T05:00",
"offsetValue": 300,
"eventState": "scheduled",
"createdAt": 1791473400000,
"updatedAt": 1791473400000
},
{
"id": "0b9d7e20-5c11-11f1-8f2a-1d3e4c5b6a70",
"shop": "your-store.myshopify.com",
"themeId": "130900000001",
"themeName": "Summer sale",
"publishDate": "2026-07-01",
"publishTime": "09:00",
"timezoneValue": "America/New_York",
"ISOString": "2026-07-01T13:00",
"offsetValue": 240,
"eventState": "failed",
"failureReason": "Shopify could not find this theme. It may have been deleted.",
"createdAt": 1782910800000,
"updatedAt": 1782910800000
}
]
}
POST Create a schedule
Send the local date and time plus a timezone, and the server works out the exact time.
curl -X POST "https://app.getthemescheduler.com/api/public/schedules" \
-H "Authorization: Bearer $THEME_SCHEDULER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"shop": "your-store.myshopify.com",
"themeId": "130912345678",
"themeName": "Black Friday",
"publishDate": "2026-11-27",
"publishTime": "00:00",
"timezoneValue": "America/New_York"
}'
Response 200:
{ "success": true, "id": "6f1c2a40-8d2e-11f1-9a3b-5b1f0c2d7e11" }
| Field | Type | Description |
|---|---|---|
shop | string, required | Your store's .myshopify.com domain, without https:// |
themeId | string or number, required | The numeric Shopify theme ID. In your Shopify admin, click Customize on the theme: it's the number after /themes/ in the address bar. |
themeName | string | The name shown in the app's schedule list. Send the theme's name. |
publishDate | string | YYYY-MM-DD in timezoneValue |
publishTime | string | HH:mm, 24-hour, in timezoneValue |
timezoneValue | string | An IANA timezone name, such as America/New_York. See timezone fields. |
ISOString | string | Older option: the publish time in UTC, YYYY-MM-DDTHH:mm. See below. |
Send publishDate, publishTime and timezoneValue together. The time has to be at least three minutes from now, or you get a 400.
Older integrations: a request with ISOString is stored as sent. The server doesn't convert or check it, so it must be a future UTC time, and publishDate, publishTime and timezoneValue are only used to show the schedule in the app. When both are sent, ISOString wins.
The theme isn't checked when you create a schedule. A trial theme, or one deleted before its time, ends up as a failed schedule with a failureReason.
There's no update method. To change a schedule, delete it and create a new one.
DELETE Delete a schedule
Removes a schedule from the queue, so its theme won't be published. Send shop and the schedule's id in the JSON body.
curl -X DELETE "https://app.getthemescheduler.com/api/public/schedules" \
-H "Authorization: Bearer $THEME_SCHEDULER_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "shop": "your-store.myshopify.com", "id": "6f1c2a40-8d2e-11f1-9a3b-5b1f0c2d7e11" }'
Response 200:
{ "success": true }
The schedule object
| Field | Description |
|---|---|
id | Schedule ID, used to delete it |
shop | The store's .myshopify.com domain |
themeId, themeName | The theme to publish, as sent when the schedule was created |
publishDate, publishTime, timezoneValue | The local publish date and time, and its timezone |
ISOString | The publish time in UTC, YYYY-MM-DDTHH:mm |
offsetValue | The timezone's offset in minutes at the publish time, positive west of UTC |
eventState | scheduled, complete or failed |
failureReason | Only on failed schedules: a short reason, such as a trial theme or lost access to the store |
createdAt, updatedAt | Milliseconds since January 1, 1970 UTC |
Older schedules can have extra fields. Ignore fields you don't recognize.
Timezone fields
timezoneValueis an IANA name, such asAmerica/New_York,Europe/BerlinorUTC. Offsets such as+05:30are refused.publishDateandpublishTimeare the wall-clock time in that timezone.ISOStringis the same moment in UTC, worked out by the server. It's when the theme publishes.offsetValuehas the same sign as JavaScript'sDate.getTimezoneOffset(): New York in winter is300, in summer240, Berlin in winter is-60.
Daylight saving time: a local time skipped when clocks go forward moves to the first valid time after the change, and the schedule's publishDate and publishTime show that time. For example, 02:30 on March 14, 2027 in New York becomes 03:00. A local time that happens twice when clocks go back uses the first one.
Errors
Errors return a JSON body with a message:
{ "status": "failed", "message": "Unauthorized" }
| Status | When | Message |
|---|---|---|
400 | GET without shop | Must provide shop query parameter. |
400 | POST without shop | Must provide shop post parameter. |
400 | DELETE without id or shop | Must provide id and shop post parameter. |
400 | POST with a missing or invalid date, time or timezone | Publish date is required. Publish time is required. Choose a valid timezone. Publish date and time are not valid. Publish date and time must be at least three minutes from now. |
401 | The API key is missing or wrong, or belongs to another store | Unauthorized |
404 | DELETE for a schedule that doesn't exist or belongs to another store | Schedule not found |
405 | Any other method, such as PUT. The Allow header lists GET, POST, DELETE. | Method not allowed |
The shop check comes before the key check, so a request without shop gets a 400 even without a key. If you get a 5xx, try again, and contact support if it keeps happening.
The API comes with every Theme Scheduler subscription: $6.95/month after a 14-day free trial.
Get it on the Shopify App Store