Schedule an offer

API v2 is in public beta: endpoints and fields can change before general availability. See the changelog

POST/preorders/offers/{id}/schedule

Costs 2 rate-limit points · Rate limits

Schedule a preorder offer: start only (off until then), end only (on until then) or both (on between them).

Send start, end or both; absent or null leaves that side open. Like the editor, start only or a window turns the offer off until the start, and end only turns it on until the end. Changing the kind of schedule turns the countdown off, reported in also_changed. When the countdown is on or the merchant also wants one, say before proposing that scheduling turns it off, and schedule first, then turn the countdown on. Use unschedule to remove the schedule.

Also searched asset scheduleschedule launchset start dateset end dateschedule offer

Path parameters

idstringRequired

Headers

Idempotency-Keystring
A fresh unique key for every write (a new UUID, say); reuse it only to retry that write. Keys are remembered for 1 hour: the same key and the same request within that hour returns the first result, with Idempotent-Replayed: true, without running again; the same key with a different method, path or body is refused (422 idempotency_key_reused); a retry while the first is still running gets 409 idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.

Request body

startstring
Example: 2026-07-01T09:00
endstring
Example: 2026-07-31T23:59

Returns

idstring
Example: 73a74948-2b57-4cc3-971f-2b441828c977
namestring
Example: Summer Sneaker Drop
internal_namestring
Example: summer-2026
availabilityobject
Show 4 child attributesHide child attributes
- schedulestring
  Example: date_range
- starts_atstring
  Example: 2026-07-01T09:00:00-04:00
- ends_atstring
  Example: 2026-07-31T23:59:00-04:00
- current_statusstring
  Example: scheduled

Errors

401

Missing or invalid X-Auth-Token.

404

The resource does not exist for this shop, or the action path is not registered.

409

Invalid lifecycle transition: read the message; don't retry blindly. Also returned while an earlier request with the same Idempotency-Key is still running.

422

The request failed validation.

429

Rate limited: cost-weighted per token (read 1, write 2; 360 points / 60s). Check Retry-After.

Every error has the same shape: see Errors.

POST/preorders/offers/{id}/schedule

curl -X POST "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/schedule" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2026-07-01T09:00",
    "end": "2026-07-31T23:59"
  }'

const res = await fetch("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/schedule", {
  method: "POST",
  headers: {
    "X-Auth-Token": process.env.STOQ_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "start": "2026-07-01T09:00",
    "end": "2026-07-31T23:59"
  }),
});
const data = await res.json();

import os
import requests

res = requests.post(
    "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/schedule",
    headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
    json={
        "start": "2026-07-01T09:00",
        "end": "2026-07-31T23:59"
    },
)
data = res.json()

require "net/http"
require "json"

uri = URI("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/schedule")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"], "Content-Type" => "application/json")
req.body = {
  start: "2026-07-01T09:00",
  end: "2026-07-31T23:59"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

Response

{
  "id": "73a74948-2b57-4cc3-971f-2b441828c977",
  "name": "Summer Sneaker Drop",
  "internal_name": "summer-2026",
  "availability": {
    "schedule": "date_range",
    "starts_at": "2026-07-01T09:00:00-04:00",
    "ends_at": "2026-07-31T23:59:00-04:00",
    "current_status": "scheduled"
  }
}

{
  "job_id": "job_a1b2c3",
  "status_url": "/api/v2/external/jobs/job_a1b2c3"
}

{
  "errors": [
    "Invalid API key"
  ],
  "code": "auth_invalid",
  "details": [
    {
      "code": "auth_invalid",
      "message": "Invalid API key",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}

{
  "errors": [
    "Offer not found"
  ],
  "code": "not_found",
  "details": [
    {
      "code": "not_found",
      "message": "Offer not found",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}

{
  "errors": [
    "Offer is already disabled"
  ],
  "code": "conflict",
  "details": [
    {
      "code": "conflict",
      "message": "Offer is already disabled",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}

{
  "errors": [
    "name is required"
  ],
  "code": "validation_failed",
  "details": [
    {
      "code": "validation_failed",
      "message": "name is required",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}

{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited",
  "details": [
    {
      "code": "rate_limited",
      "message": "Rate limit exceeded",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}