Offer¶
An offer defines how a product is presented to DSPs: release/pre-order dates, genre subgenres, usage flags and the DSP upload identifications that govern where the product is delivered. Multiple offers can exist for the same product.
Lists Offers¶
GET https://domain.com/api/v1/offers
Headers¶
| Name | Type | Description |
|---|---|---|
| Authorization* | String | Bearer \ |
| Content-Type* | String | application/vnd.api+json |
Response — 200 OK
{
"data": [
{
"type": "offers",
"id": "<ID>",
"attributes": {
"release-date": "2023-10-01T00:00:00.000000Z",
"release-type": "normal",
"preorder-date": null,
"is-default": true,
"active": true,
"status": "active",
"options": null,
"usage": {
"download": true,
"copy_scan": true,
"on_demand_stream": true,
"non_interactive_stream": true
},
"is-validated": false,
"created-at": "2023-08-11T20:45:10.000000Z",
"updated-at": "2023-08-11T20:46:07.000000Z"
},
"relationships": {
"product": {
"links": {
"related": "https://domain.com/api/v1/offers/<ID>/product",
"self": "https://domain.com/api/v1/offers/<ID>/relationships/product"
}
},
"subgenre": {
"links": {
"related": "https://domain.com/api/v1/offers/<ID>/subgenre",
"self": "https://domain.com/api/v1/offers/<ID>/relationships/subgenre"
}
},
"subgenre2": {
"links": {
"related": "https://domain.com/api/v1/offers/<ID>/subgenre2",
"self": "https://domain.com/api/v1/offers/<ID>/relationships/subgenre2"
}
},
"dsp-upload-identifications": {
"links": {
"related": "https://domain.com/api/v1/offers/<ID>/dsp-upload-identifications",
"self": "https://domain.com/api/v1/offers/<ID>/relationships/dsp-upload-identifications"
}
}
},
"links": {
"self": "https://domain.com/api/v1/offers/<ID>"
}
}
],
"meta": {
"page": {
"currentPage": 1,
"from": 1,
"lastPage": 1,
"perPage": 20,
"to": 1,
"total": 1
}
},
"jsonapi": {
"version": "1.0"
},
"links": {
"first": "https://domain.com/api/v1/offers?page[number]=1&page[size]=20",
"last": "https://domain.com/api/v1/offers?page[number]=1&page[size]=20"
}
}
Filters¶
| Filter | Example |
|---|---|
| ID | /offers?filter[id]=1 |
| Is default | /offers?filter[is-default]=true |
| Product ID | /offers?filter[product-id]=42 |
Get Offer¶
GET https://domain.com/api/v1/offers/:id
Path Parameters¶
| Name | Type | Description |
|---|---|---|
| id* | Number | Offer ID |
Headers¶
| Name | Type | Description |
|---|---|---|
| Authorization* | String | Bearer \ |
| Content-Type* | String | application/vnd.api+json |
Response — 200 OK
{
"data": {
"type": "offers",
"id": "<ID>",
"attributes": {
"release-date": "2023-10-01T00:00:00.000000Z",
"release-type": "normal",
"preorder-date": null,
"is-default": true,
"active": true,
"status": "active",
"options": null,
"usage": {
"download": true,
"copy_scan": true,
"on_demand_stream": true,
"non_interactive_stream": true
},
"is-validated": false,
"created-at": "2023-08-11T20:45:10.000000Z",
"updated-at": "2023-08-11T20:46:07.000000Z"
},
"relationships": {
"product": {
"links": {
"related": "https://domain.com/api/v1/offers/<ID>/product",
"self": "https://domain.com/api/v1/offers/<ID>/relationships/product"
}
},
"subgenre": {
"links": {
"related": "https://domain.com/api/v1/offers/<ID>/subgenre",
"self": "https://domain.com/api/v1/offers/<ID>/relationships/subgenre"
}
},
"subgenre2": {
"links": {
"related": "https://domain.com/api/v1/offers/<ID>/subgenre2",
"self": "https://domain.com/api/v1/offers/<ID>/relationships/subgenre2"
}
},
"dsp-upload-identifications": {
"links": {
"related": "https://domain.com/api/v1/offers/<ID>/dsp-upload-identifications",
"self": "https://domain.com/api/v1/offers/<ID>/relationships/dsp-upload-identifications"
}
}
},
"links": {
"self": "https://domain.com/api/v1/offers/<ID>"
}
},
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://domain.com/api/v1/offers/<ID>"
}
}
Create Offer¶
POST https://domain.com/api/v1/offers
A DSP-specific offer must set is-default: false and include at least one dsp-upload-identifications to be activated. The default offer must NOT contain DSP information and cannot be active at creation.
Headers¶
| Name | Type | Description |
|---|---|---|
| Authorization* | String | Bearer \ |
| Content-Type* | String | application/vnd.api+json |
Request Body¶
| Name | Required | Type | Description |
|---|---|---|---|
| release-date | Yes | String | Date, e.g. 2023-10-01 |
| is-default | Yes | Boolean | false for a DSP-specific offer |
| status | Yes | String | draft or active |
| product | Yes | Object | Product resource (relationship) |
| subgenre | Yes | Object | DistributorProductSubGenre resource (relationship) |
| preorder-date | No | String | Pre-order start date |
| usage | No | Object | { "download": true, "copy_scan": true, "on_demand_stream": true, "non_interactive_stream": true } |
| options | No | Object | Arbitrary key/value options |
| subgenre2 | No | Object | DistributorProductSubGenre resource (relationship) |
| dsp-upload-identifications | No | Array | DspUploadIdentification resources (relationship) |
Response — 201 Created
{
"data": {
"type": "offers",
"id": "<ID>",
"attributes": {
"release-date": "2023-10-01T00:00:00.000000Z",
"release-type": "normal",
"preorder-date": null,
"is-default": false,
"active": true,
"status": "active",
"options": null,
"usage": {
"download": true,
"copy_scan": true,
"on_demand_stream": true,
"non_interactive_stream": true
},
"is-validated": false,
"created-at": "2023-08-11T20:45:10.000000Z",
"updated-at": "2023-08-11T20:46:07.000000Z"
},
"relationships": {
"product": {
"links": {
"related": "https://domain.com/api/v1/offers/<ID>/product",
"self": "https://domain.com/api/v1/offers/<ID>/relationships/product"
}
},
"subgenre": {
"links": {
"related": "https://domain.com/api/v1/offers/<ID>/subgenre",
"self": "https://domain.com/api/v1/offers/<ID>/relationships/subgenre"
}
},
"subgenre2": {
"links": {
"related": "https://domain.com/api/v1/offers/<ID>/subgenre2",
"self": "https://domain.com/api/v1/offers/<ID>/relationships/subgenre2"
}
},
"dsp-upload-identifications": {
"links": {
"related": "https://domain.com/api/v1/offers/<ID>/dsp-upload-identifications",
"self": "https://domain.com/api/v1/offers/<ID>/relationships/dsp-upload-identifications"
}
}
},
"links": {
"self": "https://domain.com/api/v1/offers/<ID>"
}
},
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://domain.com/api/v1/offers/<ID>"
}
}
Response — 422 Unprocessable Entity
{
"jsonapi": {
"version": "1.0"
},
"errors": [
{
"detail": "The release-date field is required.",
"source": {
"pointer": "/data/attributes/release-date"
},
"status": "422",
"title": "Unprocessable Entity"
}
]
}
Update Offer¶
PATCH https://domain.com/api/v1/offers/:id
To activate an offer set status: "active" — the offer must have a release-date, a product, a subgenre and (for non-default offers) at least one dsp-upload-identifications. A default offer cannot be changed to non-default.
Path Parameters¶
| Name | Type | Description |
|---|---|---|
| id* | Number | Offer ID |
Headers¶
| Name | Type | Description |
|---|---|---|
| Authorization* | String | Bearer \ |
| Content-Type* | String | application/vnd.api+json |
Request Body¶
All fields are optional on PATCH; omitted attributes keep their current values.
| Name | Required | Type | Description |
|---|---|---|---|
| release-date | No | String | Date, e.g. 2023-10-01 |
| status | No | String | draft or active |
| preorder-date | No | String | Pre-order start date |
| usage | No | Object | Usage flags |
| options | No | Object | Arbitrary key/value options |
| subgenre | No | Object | DistributorProductSubGenre resource (relationship) |
| subgenre2 | No | Object | DistributorProductSubGenre resource (relationship) |
| dsp-upload-identifications | No | Array | DspUploadIdentification resources (relationship) |
Response — 200 OK
{
"data": {
"type": "offers",
"id": "<ID>",
"attributes": {
"release-date": "2023-10-01T00:00:00.000000Z",
"release-type": "normal",
"preorder-date": null,
"is-default": true,
"active": true,
"status": "active",
"options": null,
"usage": {
"download": true,
"copy_scan": true,
"on_demand_stream": true,
"non_interactive_stream": true
},
"is-validated": false,
"created-at": "2023-08-11T20:45:10.000000Z",
"updated-at": "2023-08-11T20:46:07.000000Z"
},
"relationships": {
"product": {
"links": {
"related": "https://domain.com/api/v1/offers/<ID>/product",
"self": "https://domain.com/api/v1/offers/<ID>/relationships/product"
}
},
"subgenre": {
"links": {
"related": "https://domain.com/api/v1/offers/<ID>/subgenre",
"self": "https://domain.com/api/v1/offers/<ID>/relationships/subgenre"
}
},
"subgenre2": {
"links": {
"related": "https://domain.com/api/v1/offers/<ID>/subgenre2",
"self": "https://domain.com/api/v1/offers/<ID>/relationships/subgenre2"
}
},
"dsp-upload-identifications": {
"links": {
"related": "https://domain.com/api/v1/offers/<ID>/dsp-upload-identifications",
"self": "https://domain.com/api/v1/offers/<ID>/relationships/dsp-upload-identifications"
}
}
},
"links": {
"self": "https://domain.com/api/v1/offers/<ID>"
}
},
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://domain.com/api/v1/offers/<ID>"
}
}
Delete Offer¶
DELETE https://domain.com/api/v1/offers/:id
Path Parameters¶
| Name | Type | Description |
|---|---|---|
| id* | Number | Offer ID |
Headers¶
| Name | Type | Description |
|---|---|---|
| Authorization* | String | Bearer \ |
| Content-Type* | String | application/vnd.api+json |
Response — 204 No Content (delete OK, empty body)
Response — 404 Not Found