Revelator Logo API

Sale Start Dates

Use these endpoints to retrieve and save the sale start dates of a release being prepared for distribution: the date and time the release goes live in stores, and an optional preorder date.

Sale start dates are defined at two levels:

  • Release level: one set of dates that applies to every store. This is the common case.
  • Store level: optional per-store dates that replace the release-level dates for one store, for staggered go-live or store exclusives.

These endpoints replace the sale start and preorder fields of the V1.0 POST /content/release/retail/save endpoint.

Do not use POST /content/release/retail/save for sale start dates. The V1.0 endpoint is deprecated and still writes to the same sale start dates. Every call to it—even one that does not include any sale start fields—replaces the release-level dates with the values in its request and deletes all per-store dates.

If your integration still calls retail/save, call it before saving sale start dates through these endpoints.


How Dates Are Resolved

For each store a release is delivered to, the applied dates are chosen as follows:

  1. If distributorStores contains an entry for the store, that entry is used.
  2. Otherwise, the release entry is used.

A store entry replaces the release-level entry for that store—fields are not merged one by one. For example, a store entry with saleStartDate: null makes that store go live as soon as possible, even when the release-level date is fixed.

An entry for a store the release is not delivered to has no effect. Store IDs come from GET /common/lookup/stores?activeOnly=true on the V1.0 API—see Store Availability.


Common Scenarios

1. Same Date Everywhere

Goal: Release goes live on 4 December 2026 in every store.

  • Release: saleStartDate: 2026-12-04.
  • Stores: None.
  • Result: All stores go live on 4 December.

2. Store Exclusive Window

Goal: iTunes/Apple Music gets the release one week before every other store.

  • Release: saleStartDate: 2026-12-11.
  • Store (iTunes/Apple Music): saleStartDate: 2026-12-04.
  • Result: iTunes/Apple Music goes live on 4 December. All other stores go live on 11 December.

If the release-level entry also sets saleStartTime, saleStartTimezoneId, or salePreOrderDate, repeat the values you want in the store entry—it does not inherit them from the release level.

3. As Soon As Possible on One Store

Goal: Release has a fixed date, but Deezer should publish it as soon as it is delivered.

  • Release: saleStartDate: 2026-12-04.
  • Store (Deezer): saleStartDate: null.
  • Result: Deezer goes live as soon as possible. All other stores go live on 4 December.

4. Timed Release with Preorder

Goal: Release goes live at 11:30 Berlin time on 4 December, with preorders open from 20 November.

  • Release: saleStartDate: 2026-12-04, saleStartTime: 11:30:00, saleStartTimezoneId of Europe/Berlin, salePreOrderDate: 2026-11-20.
  • Result: Preorders open on 20 November. All stores go live at 11:30 (Europe/Berlin) on 4 December.

Date Fields

The same four fields are used in the release entry and in each distributorStores entry.

FieldFormatDescription
saleStartDateYYYY-MM-DDDate the release goes live. null or omitted means as soon as possible.
saleStartTimehh:mm:ssTime the release goes live.
saleStartTimezoneIdintegerTime zone of saleStartTime, from GET /common/lookup/timezoneIds on the V1.0 API.
salePreOrderDateYYYY-MM-DDDate preorders open.

The time zone lookup returns one entry per time zone, with a display name and its IANA identifier:

{
	"text": "Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna",
	"timezoneId": 47,
	"ianaId": "Europe/Berlin"
}

Date Rules

The release entry and every distributorStores entry must follow these rules:

  • saleStartDate cannot be in the past.
  • saleStartTime cannot be set without saleStartDate.
  • saleStartTime and saleStartTimezoneId must be set together.
  • salePreOrderDate cannot be in the past, and must be earlier than saleStartDate.

Run GET /supply-chain/v1/releases/{releaseId}/deliver/validate before delivering. It reports a saleStartDate in the past as a blocking error for the affected store—see Validations.


Original Release Date

If the release was not previously released (previouslyReleased: false on GET /catalog/v1/releases/{releaseId}), its releaseDate is set during delivery to the earliest sale start date across the stores it is delivered to.

One “as soon as possible” store sets releaseDate to the delivery date. If even one delivered store goes live as soon as possible—through a null release-level saleStartDate it inherits, or its own null entry—the release’s releaseDate is set to the first delivery date, even when every other store has a later fixed date.

Once the release goes live in its first store, releaseDate is fixed and no longer follows changes to sale start dates. For when releaseDate can still be edited, see Lock Levels.

For a previously released release, releaseDate keeps the original release date set on the release and is not changed by sale start dates.


Get Sale Start Dates

GET /supply-chain/v1/releases/{releaseId}/sale-start-dates

Returns the saved release-level sale start dates and any per-store dates for the release.

Path Parameters

Parameter Description
releaseId * integer

ID of the release whose sale start dates you want to retrieve.

Responses

object
saleStartDate string (date) | null
Date the release goes live, in YYYY-MM-DD format. null means as soon as possible.
saleStartTime string (time) | null
Time the release goes live, in hh:mm:ss format.
saleStartTimezoneId integer | null
Time zone of saleStartTime. Retrieved from GET /common/lookup/timezoneIds on the V1.0 API.
salePreOrderDate string (date) | null
Date preorders open, in YYYY-MM-DD format.
saleStartDate string (date) | null
Date the release goes live in this store, in YYYY-MM-DD format. null means as soon as possible, even when the release-level date is fixed.
saleStartTime string (time) | null
Time the release goes live in this store, in hh:mm:ss format.
saleStartTimezoneId integer | null
Time zone of saleStartTime. Retrieved from GET /common/lookup/timezoneIds on the V1.0 API.
salePreOrderDate string (date) | null
Date preorders open in this store, in YYYY-MM-DD format.
distributorStoreId integer | null
ID of the store (DSP) these dates apply to. Retrieved from GET /common/lookup/stores?activeOnly=true on the V1.0 API.
GET /supply-chain/v1/releases/{releaseId}/sale-start-dates
curl -X GET "https://platform.revelator.com/supply-chain/v1/releases/8801/sale-start-dates" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response 200
{
  "release": {
      "saleStartDate": "2026-12-04",
      "saleStartTime": "11:30:00",
      "saleStartTimezoneId": 47,
      "salePreOrderDate": "2026-11-20"
  },
  "distributorStores": [
      {
          "distributorStoreId": 7,
          "saleStartDate": null,
          "saleStartTime": null,
          "saleStartTimezoneId": null,
          "salePreOrderDate": null
      },
      {
          "distributorStoreId": 9,
          "saleStartDate": "2026-12-11",
          "saleStartTime": null,
          "saleStartTimezoneId": null,
          "salePreOrderDate": null
      }
  ]
}

Save Sale Start Dates

Full replace: the request replaces all previously saved sale start dates for the release. A store omitted from distributorStores loses its per-store dates and falls back to the release entry, and omitting release clears the release-level dates. Always submit the complete desired state.

The request is rejected with 400 Bad Request when:

  • A distributorStores entry has no distributorStoreId, or the ID is not a known store.
  • The same distributorStoreId appears more than once.
  • A saleStartTimezoneId, on the release or on any store, is not a known time zone.
  • A date or time is not in the expected format.

A release that does not exist, or is not accessible to you, returns 404 Not Found.

PUT /supply-chain/v1/releases/{releaseId}/sale-start-dates

Saves the complete set of sale start dates: one release-level entry plus optional per-store entries.

Path Parameters

Parameter Description
releaseId * integer

ID of the release whose sale start dates you want to save.

Request Body *

object
saleStartDate string (date)
Date the release goes live, in YYYY-MM-DD format. null or omitted means as soon as possible. Cannot be in the past.
saleStartTime string (time)
Time the release goes live, in hh:mm:ss format. Cannot be set without saleStartDate, and must be set together with saleStartTimezoneId.
saleStartTimezoneId integer
Time zone of saleStartTime. Must be set together with saleStartTime. Retrieved from GET /common/lookup/timezoneIds on the V1.0 API.
salePreOrderDate string (date)
Date preorders open, in YYYY-MM-DD format. Cannot be in the past, and must be earlier than saleStartDate.
saleStartDate string (date)
Date the release goes live in this store, in YYYY-MM-DD format. null or omitted means as soon as possible, even when the release-level date is fixed. Cannot be in the past.
saleStartTime string (time)
Time the release goes live in this store, in hh:mm:ss format. Cannot be set without saleStartDate, and must be set together with saleStartTimezoneId.
saleStartTimezoneId integer
Time zone of saleStartTime. Must be set together with saleStartTime. Retrieved from GET /common/lookup/timezoneIds on the V1.0 API.
salePreOrderDate string (date)
Date preorders open in this store, in YYYY-MM-DD format. Cannot be in the past, and must be earlier than saleStartDate.
distributorStoreId * integer
ID of the store (DSP) these dates apply to. Retrieved from GET /common/lookup/stores?activeOnly=true on the V1.0 API.

Responses

boolean
PUT /supply-chain/v1/releases/{releaseId}/sale-start-dates
curl -X PUT https://platform.revelator.com/supply-chain/v1/releases/8801/sale-start-dates \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"release": {
  "saleStartDate": "2026-12-04",
  "saleStartTime": "11:30:00",
  "saleStartTimezoneId": 47,
  "salePreOrderDate": "2026-11-20"
},
"distributorStores": [
  { "distributorStoreId": 9, "saleStartDate": "2026-12-11" },
  { "distributorStoreId": 7, "saleStartDate": null }
]
}'
Example response 200
true