The Avails API is built on the Partner API Framework, which offers a unified interface for externally accessible APIs. This framework allows studios, post-production houses, and other fulfillment partners to programmatically manage their video catalog on Prime Video.
Get started
To access the Avails API, you will need an MTLS certificate and an API Key. This section provides the steps to generate a Certificate Signing Request (CSR), request an MTLS certificate, and make API requests to the Avails API.
Step 1: Client creates their private key and Certificate Signing Request (CSR) using openssl.
openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr
Step 2: Client sends email to pv-partner-apis-support@amazon.com with attached client.csr. (The team will respond with a certificate within 1 business day.) The following code snippet is a suggested example.EMAIL TEMPLATE
Partner Details
PartnerName :
Partner Alias :
Partner Resource Access : [Avails-Read,Avails-Write]
Request Limit :
Attachment
Partner Certificate signing request (client.csr).
Step 3: Client receives public certificate, cacert, and API key from the Partner API team. The following code snippet provides an example of the messages you might recieve. Prod EMAIL TEMPLATE
Hi <Name/s>
Attached you’ll find your MTLS cert for PartnerApi Production environment. It will be usable only with the client.key you used to create client.csr that you sent us
Your ApiKey is: XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX. Include it in your requests as http header ‘x-api-key’
Requests with a body must have Content-Type=application/json header
The base url is https://partnerapi.primevideo.com
MTLS certs and ApiKeys provided for Sandbox environment will not work for Prod environment. You will need to request a separate MTLS cert and ApiKey to make requests against our Prod environment when you are ready
We have given you a rate limit of 10 TPS and 5 burst TPS (meaning you can have up to 5 open concurrent connections/requests at a time).
As a place to start, I would suggest doing a request to make sure you’re able to get an authenticated response. Try a GET request to https://partnerapi.primevideo.com/v1/avails/<licensor>/full-extract/some-test-alid?territory=US&businessLine=PRIME_SUBSCRIPTION. You should get a 404 status code with a response body indicating ‘Title not found for ALID some-test-alid and Licensor <licensor>’
Please let us know if you have any questions/problems!
PV PartnerApi Team
Attachment
Partner public Certificate (clientCert.pem)
CertificateAuthority public certificate (cacert.pem)
SANDBOX EMAIL TEMPLATE
Hi <Name/s>
Attached you’ll find your MTLS cert for PartnerApi Sandbox environment. It will be usable only with the client.key you used to create client.csr that you sent us.
We have created a new sandbox only vendorAlias of api_sandbox_<licensor> that you will use as vendorAlias/licensor for all your sandbox API requests.
Your ApiKey is: XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX. Include it in your requests as http header ‘x-api-key’.
Requests with a body must have Content-Type=application/json header.
Sandbox offers the exact same endpoints offered by our Prod api but with a different base url. The base url for Sandbox is https://sandbox.partnerapi.primevideo.com
The MTLS cert and ApiKey provided here will only work in the Sandbox environment. You will need to request a separate MTLS cert and ApiKey to make requests against our Prod environment when you are ready.
When creating Avails in the sandbox environment, you may use whatever ALID/SKU you want. These will not be connected nor linked to any prod titles and need not be coordinated with any real title ALID/SKU you have created in your account. Additionally, in the Sandbox you may safely use the same ALID/SKU as real titles in your prod account if you wish.
We have given you a rate limit of 4 TPS and 2 burst TPS (burst meaning you can have up to 2 open concurrent connections/requests at a time).
Note that this sandbox is not intended for long-term storage. Lifetime of a sandbox Avail is intended to be less-than 30 days.
As a place to start, I would suggest doing a request to make sure you’re able to get an authenticated response. Try a GET request to https://sandbox.partnerapi.primevideo.com/v1/avails/api_sandbox_<licensor>/full-extract/some-test-alid?territory=US&businessLine=PRIME_SUBSCRIPTION. You should get a 404 status code with a response body indicating ‘Title not found for ALID some-test-alid and Licensor api_sandbox_<licensor>’
Please let us know if you have any questions/problems!
PV PartnerApi Team
Attachment
Partner public Certificate (clientCert.pem)
CertificateAuthority public certificate (cacert.pem)
Step 4: Client uses PublicKey, Partner public certificate, and API key for calling the API.
Here are some sample integrations using different technologies.
Bash
curl --location --request PUT 'https://partnerapi.primevideo.com/v1/avails/{partnerAlias}/full-extract/{ALID}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-key: <api key>' \
--data-raw '{ "avail": <Avail json> }' \
--key ./private_key.txt --cert ./certificate.pem
Python https://requests.readthedocs.io/en/master/user/advanced/#client-side-certificates
requests.put(f'https://partnerapi.primevideo.com/v1/avails/{partnerAlias}/full-extract/{ALID}',
data={'{ "avail": <Avail json> }'},
cert=('/path/client.cert', '/path/client.key'),
headers={'x-api-key':'<api key>','Content-Type':'application/json'})
Nodejs https://nodejs.org/api/https.html#https_https_request_options_callback
const options = {
hostname: `https://partnerapi.primevideo.com/v1/avails/{partnerAlias}/full-extract/{ALID}`,
port: 443,
path: `/v1/avails/{partnerAlias}/full-extract/{ALID}`,
method: 'PUT',
headers: {
'Content-Type':'application/json',
'x-api-key':'<api key>'
},
key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
agent: false
};
const req = https.request(options, (res) => {
// ...
});
Revoke MTLS certificate access
Occasionally, an MTLS certificate may need to be revoked. If you need one of their certificates to be revoked, send the information shown in the following example via email to pv-partner-apis-support@amazon.com. EMAIL TEMPLATE
Partner Details
PartnerName :
Partner Alias :
Owner Email Id :
Certificate Serial Number :
ApiKey :
MDDF-to-EMA Avail schema mapping
We are using the MDDF Avail schema in JSON. A diagram of the schema is available from MovieLabs at the following link: https://www.movielabs.com/md/avails/v2.6/avails-v2.6.1/avails-v2.6.1.html#Link2. The following table shows the mapping from EMA for the MDDF Avail properties and attributes supported.
Prime Video MDDF JSON |
Prime Video EMA Spreadsheet |
Avail.Compatibility.SpecVersion |
1.7.3 |
Avail.ALID |
ALID |
Avail.Disposition.EntryType |
EntryType |
Avail.Licensor.DisplayName |
DisplayName |
Avail.Asset._contentID |
ALID |
Avail.Asset.WorkType |
WorkType |
Avail.Asset.Metadata.TitleInternalAliias |
TitleInternalAlias |
Avail.Asset.EpisodeMetadata.TitleInternalAliias |
EpisodeTitleInternalAlias |
Avail.Asset.EpisodeMetadata.EpisodeNumber.Number |
EpisodeNumber |
Avail.Asset.EpisodeMetadata.SeasonMetadata.SeasonTitleInternalAlias |
SeasonTitleInternalAlias |
Avail.Asset.EpisodeMetadata.SeasonMetadata.SeasonContentID |
SeasonAltID |
Avail.Asset.EpisodeMetadata.SeasonMetadata.SeasonNumber.Number |
SeasonNumber |
Avail.Asset.EpisodeMetadata.SeasonMetadata.NumberOfEpisodes |
EpisodeCount |
Avail.Asset.EpisodeMetadata.SeriesMetadata.SeriesContentID |
SeriesAldID |
Avail.Asset.EpisodeMetadata.SeriesMetadata.SeriesTitleInternalAlias |
SeriesTitleInternalAlias |
Avail.Asset.EpisodeMetadata.SeriesMetadata.NumberOfSeasons |
SeasonCount |
Avail.Asset.SeasonMetadata.SeasonTitleInternalAliias |
SeasonTitleInternalAlias |
Avail.Asset.SeasonMetadata.SeasonContentID |
SeasonAltID |
Avail.Asset.SeasonMetadata.SeasonNumber.Number |
SeasonNumber |
Avail.Asset.SeasonMetadata.NumberOfEpisodes |
EpisodeCount |
Avail.Asset.SeasonMetadata.SeriesMetadata.SeriesContentID |
SeriesAldID |
Avail.Asset.SeasonMetadata.SeriesMetadata.SeriesTitleInternalAlias |
SeriesTitleInternalAlias |
Avail.Asset.SeasonMetadata.SeriesMetadata.NumberOfSeasons |
SeasonCount |
Avail.Transaction.LicenseType |
LicenseType |
Avail.Transaction.Territory.Country |
Territory |
Avail.Transaction.Start |
Start |
Avail.Transaction.End |
End |
Avail.Transaction.AllowedLanguage |
AllowedLanguages |
Avail.Transaction.HoldbackLanguage |
HoldbackLanguage |
Avail.Transaction.AssetLanguage.value |
AssetLanguage |
Avail.Transaction.AssetLanguage._asset |
LocalizationType |
Avail.Transaction.LicenseRightsDescription |
LicenseRightsDescription |
Avail.Transaction.FormatProfile |
FormatProfile |
Avail.Transaction.ContractID |
ContractID |
Avail.Transaction.OtherInstructions |
OtherInstructions |
Avail.Transaction._TransactionID |
AvailID |
Avail.Transaction.Term._termName.ChannelIdentity |
GroupIdentity |
Avail.Transaction.Term._termName.AnnounceDate |
AnnounceDate |
Avail.Transaction.Term._termName.SuppressionLiftDate |
SuppressionLiftDate |
Avail.Transaction.Term._termName.RentalDuration |
RentalDuration |
Avail.Transaction.Term._termName.WatchDuration |
WatchDuration |
Avail.Transaction.Term._termName.Download |
Download |
Avail.Transaction.Term._termName.Tier |
PriceType |
Avail.Transaction.Term._termName.Category |
PriceType |
Avail.Transaction.Term._termName.WSP |
PriceType |
Avail.Transaction.Term._termName.SRP |
SRP |
Avail.Transaction.Term.Money.value |
Price |
Avail.Transaction.Term.Money._currency |
PriceCurrency |
Avail.Transaction.Term.Exclusivity |
Exclusivity |
Avail.Transaction.Term.ExclusiveAttributes |
ExclusiveAttributes |
Avail.SharedEntitlement.EcosystemID |
DMA_ID |
Avail.SharedEntitlement.ecosystem |
DMA_ID |
Methods
The following sections describe the different API request methods you can use with the Avails API, including their specific endpoints, and what the body of each request and response should look like.
Category: Full Extract
GET:
- Endpoint:
/avails/{licensor}/full-extract/{ALID}?territory={territory}&businessLine={businessLine} - RequestBody: -
- ResponseBody: Avail with transactions for one scope
PUT:
- Endpoint:
/avails/{licensor}/full-extract/{ALID} - RequestBody:
{ ... Avail data } - ResponseBody: Success/Failure response
DELETE:
- Endpoint:
/avails/{licensor}/full-extract/{ALID}?territory={territory}&businessLine={businessLine}&contractID={CPH | FIXED_FEE}&channelIdentity={channelIdentity} - RequestBody: -
- ResponseBody: Success/Failure response
POST:
- Endpoint:
/avails/{licensor}/full-extract/{ALID}/validate - RequestBody:
{ ... Avail data } - ResponseBody: Success/Failure response
Category: Batch
Sub Category: Full Extract
POST:
- Endpoint:
/avails/full-extract/batch/get - RequestBody:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}?territory={territory}&businessLine={businessLine}' }... ] } - ResponseBody:
[ { 'requestItemId':'<requestId>', 'success':'<true | false>', 'avail':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
POST:
- Endpoint:
/avails/full-extract/batch/put - RequestBody:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}' 'body': { avails: [<Avail data>] } }... ] } - ResponseBody:
[ { 'requestId':'<requestId>', 'statusCode':'<statusCode>', 'body':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
POST:
- Endpoint:
/avails/full-extract/batch/delete - RequestBody:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}?territory={territory}&businessLine={businessLine}&contractId={CPH | FIXED_FEE}&channelIdentity={channelIdentity}' }... ] } - ResponseBody:
[ { 'requestId':'<requestId>', 'statusCode':'<statusCode>', 'body':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
POST:
- Endpoint:
/avails/full-extract/batch/validate - RequestBody:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}/validate' 'body': { avails: [<Avail data>] } }... ] } - ResponseBody:
[ { 'requestId':'<requestId>', 'statusCode':'<statusCode>', 'body':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
Business lines
For Full Extract, all Avails for a business line + territory must be delivered together. The following business lines are supported:
- PRIME_SUBSCRIPTION
- TVOD
- FVOD
- CHANNELS
BusinessLine values can be determined by the combination of LicenseType and BenefitId as shown in the following table.
LicenseType |
BenefitId |
BusinessLine |
EST |
- |
TVOD |
VOD |
- |
TVOD |
POEST |
- |
TVOD |
SVOD |
PRIME |
PRIME_SUBSCRIPTION |
SVOD |
A4K |
PRIME_SUBSCRIPTION |
SVOD |
ANY (not PRIME or A4K) |
CHANNELS |
FVOD |
ANY |
FVOD |
