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 parameterDescription
shop, requiredYour 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" }
FieldTypeDescription
shopstring, requiredYour store's .myshopify.com domain, without https://
themeIdstring or number, requiredThe numeric Shopify theme ID. In your Shopify admin, click Customize on the theme: it's the number after /themes/ in the address bar.
themeNamestringThe name shown in the app's schedule list. Send the theme's name.
publishDatestringYYYY-MM-DD in timezoneValue
publishTimestringHH:mm, 24-hour, in timezoneValue
timezoneValuestringAn IANA timezone name, such as America/New_York. See timezone fields.
ISOStringstringOlder 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

FieldDescription
idSchedule ID, used to delete it
shopThe store's .myshopify.com domain
themeId, themeNameThe theme to publish, as sent when the schedule was created
publishDate, publishTime, timezoneValueThe local publish date and time, and its timezone
ISOStringThe publish time in UTC, YYYY-MM-DDTHH:mm
offsetValueThe timezone's offset in minutes at the publish time, positive west of UTC
eventStatescheduled, complete or failed
failureReasonOnly on failed schedules: a short reason, such as a trial theme or lost access to the store
createdAt, updatedAtMilliseconds since January 1, 1970 UTC

Older schedules can have extra fields. Ignore fields you don't recognize.

Timezone fields

  • timezoneValue is an IANA name, such as America/New_York, Europe/Berlin or UTC. Offsets such as +05:30 are refused.
  • publishDate and publishTime are the wall-clock time in that timezone.
  • ISOString is the same moment in UTC, worked out by the server. It's when the theme publishes.
  • offsetValue has the same sign as JavaScript's Date.getTimezoneOffset(): New York in winter is 300, in summer 240, 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" }
StatusWhenMessage
400GET without shopMust provide shop query parameter.
400POST without shopMust provide shop post parameter.
400DELETE without id or shopMust provide id and shop post parameter.
400POST with a missing or invalid date, time or timezonePublish 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.
401The API key is missing or wrong, or belongs to another storeUnauthorized
404DELETE for a schedule that doesn't exist or belongs to another storeSchedule not found
405Any 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