Offer

List Offers

GET https://api.idol.io/api/v2/offers

Headers

Name	Type	Description
Authorization*	string	Bearer <token>
Content-Type*	string	application/vnd.api+json

200

{
  "data": [
    {
      "id": "<ID>",
      "type": "offers",
      "links": {
        "self": "https://api.idol.io/api/v2/offers/<ID>"
      },
      "attributes": {
        "created-at": "2024-08-30T18:52:22.000+02:00",
        "updated-at": "2024-05-28T12:37:08.656+02:00",
        "release-date": "2024-08-27T00:00:00.000Z",
        "release-type": "normal",
        "preorder-date": null,
        "pitch-date": null,
        "is-default": true,
        "active": true,
        "options": {},
        "usage": {
          "download": true,
          "on_demand_stream": true,
          "non_interactive_stream": true,
          "copy_scan": true
        },
        "is-validated": false
      },
      "relationships": {
        "dsp-upload-identifications": {
          "links": {
            "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/dsp-upload-identifications",
            "related": "https://api.idol.io/api/v2/offers/<ID>/dsp-upload-identifications"
          }
        },
        "product": {
          "links": {
            "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/product",
            "related": "https://api.idol.io/api/v2/offers/<ID>/product"
          },
          "data": {
            "type": "products",
            "id": "<ID>"
          }
        },
        "subgenre": {
          "links": {
            "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/subgenre",
            "related": "https://api.idol.io/api/v2/offers/<ID>/subgenre"
          },
          "data": {
            "type": "distributor-product-subgenres",
            "id": "<ID>"
          }
        },
        "subgenre2": {
          "links": {
            "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/subgenre2",
            "related": "https://api.idol.io/api/v2/offers/<ID>/subgenre2"
          },
          "data": null
        },
        "price-code": {
          "links": {
            "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/price-code",
            "related": "https://api.idol.io/api/v2/offers/<ID>/price-code"
          },
          "data": {
            "type": "distributor-price-codes",
            "id": "<ID>"
          }
        },
        "track-price-code": {
          "links": {
            "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/track-price-code",
            "related": "https://api.idol.io/api/v2/offers/<ID>/track-price-code"
          },
          "data": {
            "type": "distributor-price-codes",
            "id": "<ID>"
          }
        }
      }
    },
    {
      "id": "<ID>",
      "type": "offers",
      "links": {
        "self": "https://api.idol.io/api/v2/offers/<ID>"
      },
      "attributes": {
        "created-at": "2023-08-30T18:53:02.000+02:00",
        "updated-at": "2023-03-03T15:23:14.055+01:00",
        "release-date": "2012-08-28T00:00:00.000Z",
        "release-type": "normal",
        "preorder-date": null,
        "pitch-date": null,
        "is-default": true,
        "active": true,
        "options": {},
        "usage": {
          "download": true,
          "on_demand_stream": true,
          "non_interactive_stream": true,
          "copy_scan": true
        },
        "is-validated": true
      },
      "relationships": {
        "dsp-upload-identifications": {
          "links": {
            "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/dsp-upload-identifications",
            "related": "https://api.idol.io/api/v2/offers/<ID>/dsp-upload-identifications"
          }
        },
        "product": {
          "links": {
            "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/product",
            "related": "https://api.idol.io/api/v2/offers/<ID>/product"
          },
          "data": {
            "type": "products",
            "id": "<ID>"
          }
        },
        "subgenre": {
          "links": {
            "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/subgenre",
            "related": "https://api.idol.io/api/v2/offers/<ID>/subgenre"
          },
          "data": {
            "type": "distributor-product-subgenres",
            "id": "<ID>"
          }
        },
        "subgenre2": {
          "links": {
            "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/subgenre2",
            "related": "https://api.idol.io/api/v2/offers/<ID>/subgenre2"
          },
          "data": null
        },
        "price-code": {
          "links": {
            "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/price-code",
            "related": "https://api.idol.io/api/v2/offers/<ID>/price-code"
          },
          "data": {
            "type": "distributor-price-codes",
            "id": "<ID>"
          }
        },
        "track-price-code": {
          "links": {
            "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/track-price-code",
            "related": "https://api.idol.io/api/v2/offers/<ID>/track-price-code"
          },
          "data": {
            "type": "distributor-price-codes",
            "id": "<ID>"
          }
        }
      }
    },
    {
      "id": "<ID>",
      "type": "offers",
      "links": {
        "self": "https://api.idol.io/api/v2/offers/<ID>"
      },
      "attributes": {
        "created-at": "2020-08-30T18:53:29.000+02:00",
        "updated-at": "2023-03-03T15:23:14.085+01:00",
        "release-date": "2020-08-29T00:00:00.000Z",
        "release-type": "normal",
        "preorder-date": null,
        "pitch-date": null,
        "is-default": true,
        "active": true,
        "options": {},
        "usage": {
          "download": true,
          "on_demand_stream": true,
          "non_interactive_stream": true,
          "copy_scan": true
        },
        "is-validated": false
      },
      "relationships": {
        "dsp-upload-identifications": {
          "links": {
            "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/dsp-upload-identifications",
            "related": "https://api.idol.io/api/v2/offers/<ID>/dsp-upload-identifications"
          }
        },
        "product": {
          "links": {
            "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/product",
            "related": "https://api.idol.io/api/v2/offers/<ID>/product"
          },
          "data": {
            "type": "products",
            "id": "<ID>"
          }
        },
        "subgenre": {
          "links": {
            "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/subgenre",
            "related": "https://api.idol.io/api/v2/offers/<ID>/subgenre"
          },
          "data": {
            "type": "distributor-product-subgenres",
            "id": "<ID>"
          }
        },
        "subgenre2": {
          "links": {
            "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/subgenre2",
            "related": "https://api.idol.io/api/v2/offers/<ID>/subgenre2"
          },
          "data": null
        },
        "price-code": {
          "links": {
            "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/price-code",
            "related": "https://api.idol.io/api/v2/offers/<ID>/price-code"
          },
          "data": {
            "type": "distributor-price-codes",
            "id": "<ID>"
          }
        },
        "track-price-code": {
          "links": {
            "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/track-price-code",
            "related": "https://api.idol.io/api/v2/offers/<ID>/track-price-code"
          },
          "data": {
            "type": "distributor-price-codes",
            "id": "<ID>"
          }
        }
      }
    }
  ],
  "meta": {
    "record-count": 120,
    "page-count": 40
  },
  "links": {
    "first": "https://api.idol.io/api/v2/offers?page%5Bnumber%5D=1&page%5Bsize%5D=3",
    "next": "https://api.idol.io/api/v2/offers?page%5Bnumber%5D=2&page%5Bsize%5D=3",
    "last": "https://api.idol.io/api/v2/offers?page%5Bnumber%5D=40&page%5Bsize%5D=3"
  }
}

Filter resources

Distributor

api/v2/offers?filter[distributor-id]=true

Companies

api/v2/offers?filter[company-ids]=1,2

Labels

api/v2/offers?filter[label-ids]=1,2

Products

api/v2/offers?filter[product-ids]=1,2

Artists

api/v2/offers?filter[artist-ids]=1,2

Active

api/v2/offers?filter[active]=true

IsDefault

api/v2/offers?filter[is-default]=true

Get Offer

GET https://api.idol.io/api/v2/offers/:id

Path Parameters

Name	Type	Description
id*	number	ID of the Offer

Headers

Name	Type	Description
Authorization*	string	Bearer <token>
Content-Type*	string	application/vnd.api+json

200

{
  "data": {
    "id": "<ID>",
    "type": "offers",
    "links": {
      "self": "https://api.idol.io/api/v2/offers/<ID>"
    },
    "attributes": {
      "created-at": "2022-08-30T18:52:22.000+02:00",
      "updated-at": "2024-05-28T12:37:08.656+02:00",
      "release-date": "2022-08-27T00:00:00.000Z",
      "release-type": "normal",
      "preorder-date": null,
      "is-default": true,
      "active": true,
      "options": {},
      "usage": {
        "download": true,
        "on_demand_stream": true,
        "non_interactive_stream": true,
        "copy_scan": true
      },
      "is-validated": false
    },
    "relationships": {
      "dsp-upload-identifications": {
        "links": {
          "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/dsp-upload-identifications",
          "related": "https://api.idol.io/api/v2/offers/<ID>/dsp-upload-identifications"
        }
      },
      "product": {
        "links": {
          "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/product",
          "related": "https://api.idol.io/api/v2/offers/<ID>/product"
        },
        "data": {
          "type": "products",
          "id": "<ID>"
        }
      },
      "subgenre": {
        "links": {
          "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/subgenre",
          "related": "https://api.idol.io/api/v2/offers/<ID>/subgenre"
        },
        "data": {
          "type": "distributor-product-subgenres",
          "id": "<ID>"
        }
      },
      "subgenre2": {
        "links": {
          "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/subgenre2",
          "related": "https://api.idol.io/api/v2/offers/<ID>/subgenre2"
        },
        "data": null
      },
      "price-code": {
        "links": {
          "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/price-code",
          "related": "https://api.idol.io/api/v2/offers/<ID>/price-code"
        },
        "data": {
          "type": "distributor-price-codes",
          "id": "<ID>"
        }
      },
      "track-price-code": {
        "links": {
          "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/track-price-code",
          "related": "https://api.idol.io/api/v2/offers/<ID>/track-price-code"
        },
        "data": {
          "type": "distributor-price-codes",
          "id": "<ID>"
        }
      }
    }
  }
}

Create Offer

POST https://api.idol.io/api/v2/offers

Headers

Name	Type	Description
Authorization*	string	Bearer <token>
Content-Type*	string	application/vnd.api+json

Request Body

Name	Type	Description
product*	object	Product Object
subgenre*	object	DistributorProductSubgenre Object
subgenre2	object	DistributorProductSubgenre Object
price-code*	object	DistributorPriceCode Object
track-price-code*	object	DistributorPriceCode Object
dsp-upload-identifications	object	DspUploadIdentification Object
territories	object	Territory Object
is-default*	boolean	true
release-date*	string	date - e.g. 2023-01-01
preorder-date	string	date - e.g. 2023-01-01
pitch-date	string	date - e.g. 2023-01-01
status*	boolean	draft / active / archived
preview-before-release-date	boolean	true
usage*	object	{ "download": true, "on_demand_stream": true, "copy_scan": true, "non_interactive_stream": true }
options	array	[ { name: "custom-vendor_id", value: 6 } ]

200

{
  "data": {
    "id": "<ID>",
    "type": "offers",
    "links": {
      "self": "https://api.idol.io/api/v2/offers/<ID>"
    },
    "attributes": {
      "created-at": "2023-07-11T12:10:29.781+02:00",
      "updated-at": "2023-07-11T12:10:29.781+02:00",
      "release-date": null,
      "release-type": "normal",
      "preorder-date": "2023-05-01T00:00:00.000Z",
      "pitch-date": "2023-05-01T00:00:00.000Z",
      "is-default": false,
      "active": true,
      "options": {
        "custom_vendor_id": "custom ID",
        "itunes_preorder_price_code_id": "<ID>"
      },
      "usage": {
        "download": true,
        "on_demand_stream": true,
        "non_interactive_stream": true,
        "copy_scan": true
      },
      "status": "draft"
    },
    "relationships": {
      "dsp-upload-identifications": {
        "links": {
          "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/dsp-upload-identifications",
          "related": "https://api.idol.io/api/v2/offers/<ID>/dsp-upload-identifications"
        }
      },
      "product": {
        "links": {
          "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/product",
          "related": "https://api.idol.io/api/v2/offers/<ID>/product"
        },
        "data": {
          "type": "products",
          "id": "<ID>"
        }
      },
      "subgenre": {
        "links": {
          "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/subgenre",
          "related": "https://api.idol.io/api/v2/offers/<ID>/subgenre"
        },
        "data": null
      },
      "subgenre2": {
        "links": {
          "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/subgenre2",
          "related": "https://api.idol.io/api/v2/offers/<ID>/subgenre2"
        },
        "data": null
      },
      "price-code": {
        "links": {
          "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/price-code",
          "related": "https://api.idol.io/api/v2/offers/<ID>/price-code"
        },
        "data": null
      },
      "track-price-code": {
        "links": {
          "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/track-price-code",
          "related": "https://api.idol.io/api/v2/offers/<ID>/track-price-code"
        },
        "data": null
      }
    }
  }
}

• Let the dsp-upload-identifications relationship empty if you want to create a default offer on a product.

• The track-price-code attribute is a DistributorPriceCode object with a is-track-price attribute set to true.

• Find more details on how to provide the options attribute here.

Update Offer

PUT https://api.idol.io/api/v2/offers

Path Parameters

Name	Type	Description
id*	number	ID of the Offer

Headers

Name	Type	Description
Authorization*	string	Bearer <token>
Content-Type*	string	application/vnd.api+json

Request Body

Name	Type	Description
product*	object	Product Object
subgenre*	object	DistributorProductSubgenre Object
subgenre2	object	DistributorProductSubgenre Object
price-code*	object	DistributorPriceCode Object
track-price-code*	object	DistributorPriceCode Object
dsp-upload-identifications	object	DspUploadIdentification Object
territories	object	Territory Object
is-default*	boolean	true
release-date*	string	date - e.g. 2023-01-01
preorder-date	string	date - e.g. 2023-01-01
pitch-date	string	date - e.g. 2023-01-01
status*	boolean	draft / active / archived
preview-before-release-date	boolean	true
usage*	object	{ "download": true, "on_demand_stream": true, "copy_scan": true, "non_interactive_stream": true }
options	array	[ { name: "custom-vendor_id", value: 6 } ]

200

{
  "data": {
    "id": "<ID>",
    "type": "offers",
    "links": {
      "self": "https://api.idol.io/api/v2/offers/<ID>"
    },
    "attributes": {
      "created-at": "2018-07-11T12:10:29.781+02:00",
      "updated-at": "2018-07-11T12:10:29.781+02:00",
      "release-date": null,
      "release-type": "normal",
      "preorder-date": "2023-05-01T00:00:00.000Z",
      "pitch-date": "2023-05-01T00:00:00.000Z",
      "is-default": false,
      "active": true,
      "options": {
        "custom_vendor_id": "custom ID",
        "itunes_preorder_price_code_id": "<ID>"
      },
      "usage": {
        "download": true,
        "on_demand_stream": true,
        "non_interactive_stream": true,
        "copy_scan": true
      },
      "status": "active"
    },
    "relationships": {
      "dsp-upload-identifications": {
        "links": {
          "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/dsp-upload-identifications",
          "related": "https://api.idol.io/api/v2/offers/<ID>/dsp-upload-identifications"
        }
      },
      "product": {
        "links": {
          "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/product",
          "related": "https://api.idol.io/api/v2/offers/<ID>/product"
        },
        "data": {
          "type": "products",
          "id": "<ID>"
        }
      },
      "subgenre": {
        "links": {
          "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/subgenre",
          "related": "https://api.idol.io/api/v2/offers/<ID>/subgenre"
        },
        "data": null
      },
      "subgenre2": {
        "links": {
          "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/subgenre2",
          "related": "https://api.idol.io/api/v2/offers/<ID>/subgenre2"
        },
        "data": null
      },
      "price-code": {
        "links": {
          "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/price-code",
          "related": "https://api.idol.io/api/v2/offers/<ID>/price-code"
        },
        "data": null
      },
      "track-price-code": {
        "links": {
          "self": "https://api.idol.io/api/v2/offers/<ID>/relationships/track-price-code",
          "related": "https://api.idol.io/api/v2/offers/<ID>/track-price-code"
        },
        "data": null
      }
    }
  }
}

• Let the dsp-upload-identifications relationship empty if you want to create a default offer on a product.

• The track-price-code attribute is a DistributorPriceCode object with a is-track-price attribute set to true.

• Find more details on how to provide the options attribute here.

Delete Offer

DELETE https://api.idol.io/api/v2/offers/:id

Path Parameters

Name	Type	Description
id*	number	ID of the Offer

Headers

Name	Type	Description
Authorization*	string	Bearer <token>
Content-Type*	string	application/vnd.api+json

200