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:
- If
distributorStorescontains an entry for the store, that entry is used. - Otherwise, the
releaseentry 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,saleStartTimezoneIdof 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.
| Field | Format | Description |
|---|---|---|
saleStartDate | YYYY-MM-DD | Date the release goes live. null or omitted means as soon as possible. |
saleStartTime | hh:mm:ss | Time the release goes live. |
saleStartTimezoneId | integer | Time zone of saleStartTime, from GET /common/lookup/timezoneIds on the V1.0 API. |
salePreOrderDate | YYYY-MM-DD | Date 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:
saleStartDatecannot be in the past.saleStartTimecannot be set withoutsaleStartDate.saleStartTimeandsaleStartTimezoneIdmust be set together.salePreOrderDatecannot be in the past, and must be earlier thansaleStartDate.
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
/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 release SaleStartDatesModel distributorStores. null when no dates have been saved for the release. saleStartDate string (date) | null YYYY-MM-DD format. null means as soon as possible. saleStartTime string (time) | null hh:mm:ss format. saleStartTimezoneId integer | null saleStartTime. Retrieved from GET /common/lookup/timezoneIds on the V1.0 API. salePreOrderDate string (date) | null YYYY-MM-DD format. distributorStores DistributorStoreSaleStartDatesModel[] | null null when no per-store dates have been saved. saleStartDate string (date) | null YYYY-MM-DD format. null means as soon as possible, even when the release-level date is fixed. saleStartTime string (time) | null hh:mm:ss format. saleStartTimezoneId integer | null saleStartTime. Retrieved from GET /common/lookup/timezoneIds on the V1.0 API. salePreOrderDate string (date) | null YYYY-MM-DD format. distributorStoreId integer | null /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" 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
}
]
} {
"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
distributorStoresentry has nodistributorStoreId, or the ID is not a known store. - The same
distributorStoreIdappears 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.
/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 release SaleStartDatesModel distributorStores. Omitting it, or sending null, clears the release-level dates. saleStartDate string (date) YYYY-MM-DD format. null or omitted means as soon as possible. Cannot be in the past. saleStartTime string (time) hh:mm:ss format. Cannot be set without saleStartDate, and must be set together with saleStartTimezoneId. saleStartTimezoneId integer saleStartTime. Must be set together with saleStartTime. Retrieved from GET /common/lookup/timezoneIds on the V1.0 API. salePreOrderDate string (date) YYYY-MM-DD format. Cannot be in the past, and must be earlier than saleStartDate. distributorStores DistributorStoreSaleStartDatesModel[] release entry. saleStartDate string (date) 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) hh:mm:ss format. Cannot be set without saleStartDate, and must be set together with saleStartTimezoneId. saleStartTimezoneId integer saleStartTime. Must be set together with saleStartTime. Retrieved from GET /common/lookup/timezoneIds on the V1.0 API. salePreOrderDate string (date) YYYY-MM-DD format. Cannot be in the past, and must be earlier than saleStartDate. distributorStoreId * integer Responses
boolean /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 }
]
}' 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 true