Users prefer to watch or listen to content that they can already access, such as
their existing subscription content. If Google knows what content a user can
access on your app or platform, then Google can deliver a more relevant
experience across Google surfaces and direct the user to that content.
![](https://developers.google.com/static/actions/media/images/image-entitlements-4.png) **Figure 1.** Access requirements help your subscribers access the content on your app or platform.

## Identify content access requirements

You must identify the access requirement for each content package in your
catalog. When you do so, consider the following questions:

- Do users need to log in to your app or platform to access the content?
- Do users need a subscription?

  **Watch Actions only:**
  - Do users need a subscription from an external service provider?
  - Do you offer a tiered, multi-package, or add-on subscription?
- **Watch Actions only:** Do users need to rent or purchase the content?

- Does the access requirement change over time?

- Does the access requirement depend on the device location?

## Access restriction types

There are two kinds of access restrictions:

- [Paywall type](https://developers.google.com/actions/media/concepts/access-requirements#paywall-type)
- [Geographic area](https://developers.google.com/actions/media/concepts/access-requirements#geographic-area)

### Paywall type

You can restrict access to content by its paywall type. The following table
details the different paywall types:

| Paywall type | Example | Category |
|---|---|---|
| No purchase or login is required. | Crackle | `nologinrequired` |
| The user must be logged in, but doesn't need a paid subscription. | Vudu (AVOD) | `free` |
| The user must have an active subscription. Access is independent of the subscription tier. | Netflix | `subscription` > [!NOTE] > **Note:** A [common > tier](https://developers.google.com/actions/media/concepts/access-requirements#common-tier) markup is required. |
| The user must have an active subscription. Access is dependent on the subscription tier. | Hulu (add-ons) | `subscription` > [!NOTE] > **Note:** Specify the set of entitlement identifiers required to access this content with `MediaSubscription.identifier`. For more information, see [Entitlement identifier](https://developers.google.com/actions/media/concepts/access-requirements#entitlement-identifier). Also, a [common tier](https://developers.google.com/actions/media/concepts/access-requirements#common-tier) markup may be required. |
| The content is available for a finite amount of time after the purchase. | Vudu | `rental` |
| The content is available for an indefinite amount of time after the purchase. | Vudu | `purchase` |
| The content is available by cable subscription. | HBO Go | `externalSubscription` |

#### Paywall type for Watch Actions

To specify the content paywall type for Watch Actions, use the
[`category`](https://developers.google.com/actions/media/reference/data-specification/watch-actions-common-specification#action_access_specification_properties)
property in the
[Action access specification](https://developers.google.com/actions/media/reference/data-specification/watch-actions-common-specification#action_access_specification_properties):

    "potentialAction": {
      "@type":"WatchAction",
      "target": { ... },
      "actionAccessibilityRequirement": {
        "@type": "ActionAccessSpecification",
        "category": "subscription",
        "availabilityStarts": "2018-06-01T10:35:29Z",
        "availabilityEnds": "2019-05-31T10:35:29Z",
        "eligibleRegion": {
          "@type": "Country",
          "name": "US"
        }
      },
      ...
    }

#### Paywall type for Listen Actions

To specify the content paywall type for Listen Actions, use the
[`category`](https://developers.google.com/actions/media/reference/data-specification/listen-actions-common-specification#action_markup_properties)
property in the
[offer object](https://developers.google.com/actions/media/reference/#offer):

    "potentialAction": {
      "@type":"ListenAction",
      "target": { ... },
      "expectsAcceptanceOf":{
        "@type":"Offer",
        "category":"subscription",
        "availabilityStarts": "2018-06-01T10:35:29Z",
        "availabilityEnds": "2019-05-31T10:35:29Z",
        "eligibleRegion": {
          "@type":"Country",
          "name":"US"
        }
      },
      ...
    }

### Geographic area

You must specify the geographic areas where the content is available. Use one or
both of the following properties:

- The `eligibleRegion` property of an [Action access specification](https://developers.google.com/actions/media/reference/data-specification/watch-actions-common-specification#action_access_specification_properties) object. This property is required.
- The `ineligibleRegion` property of an [Action access specification](https://developers.google.com/actions/media/reference/data-specification/watch-actions-common-specification#action_access_specification_properties) object.

A user can access content if the device location is within any region that's
specified in `eligibleRegion` and isn't within any region that's specified in
`ineligibleRegion`.

The `eligibleRegion` and `ineligibleRegion` properties allow the following
values:

- A list of [`Country`](https://schema.org/Country), [`City`](https://schema.org/City), and [`State`](https://schema.org/State).
- A [`GeoShape`](https://schema.org/GeoShape) object. See the [`GeoShape` properties](https://developers.google.com/actions/media/reference/data-specification/watch-actions-common-specification#geoshape_properties) section for detailed requirements.
- A list of `GeoShape` objects.

If the content is available globally, use the following special value for
`eligibleRegion`:

    "eligibleRegion": "EARTH",

#### eligibleRegion use cases

The following are use-case examples of the `eligibleRegion` property:

- **Example 1:** `eligibleRegion` with a list of countries.
- **Example 2:** `eligibleRegion` with a `GeoShape` object that contains a list of ZIP codes.
- **Example 3:** `eligibleRegion` with a `GeoShape` object that contains a list of Forward Sortation Area (FSA) codes.
- **Example 4:** `eligibleRegion` with a `GeoShape` object that contains a DMA ID.
- **Example 5:** `eligibleRegion` with a list of `GeoShape` objects. Each contains a DMA ID.
- **Example 6:** `ineligibleRegion` with blocked-out ZIP codes.

### Example 1

`eligibleRegion` with a list of countries:

```
"actionAccessibilityRequirement": {
  "@type": "ActionAccessSpecification",
  "category": "subscription",
  "requiresSubscription": {
    "@type": "MediaSubscription",
    "@id": "http://www.example.com/north_america_network/subscription",
    "name": "Example Subscription",
    "commonTier": true
  },
  "eligibleRegion": [
    {
      "@type": "Country",
      "name": "US"
    },
    {
      "@type": "Country",
      "name": "CA"
    }
  ]
}
```

### Example 2

`eligibleRegion` with a `GeoShape` object that
contains a list of ZIP codes:

```
"actionAccessibilityRequirement": {
  "@type": "ActionAccessSpecification",
  "category": "subscription",
  "requiresSubscription": {
    "@type": "MediaSubscription",
    "@id": "http://www.example.com/local_tv_network/subscription",
    "name": "Example Subscription",
    "commonTier": true
  },
  "eligibleRegion": {
    "@type": "GeoShape",
    "@id": "http://example.com/area1",
    "addressCountry": "US",
    "postalCode": [
      "94118",
      "94119"
    ]
  }
}
```

### Example 3

`eligibleRegion` with a `GeoShape` object that
contains a list of Forward Sortation Area (FSA) codes:

```
"actionAccessibilityRequirement": {
  "@type": "ActionAccessSpecification",
  "category": "subscription",
  "requiresSubscription": {
    "@type": "MediaSubscription",
    "@id": "http://www.example.com/local_tv_network/subscription",
    "name": "Example Subscription",
    "commonTier": true
  },
  "additionalProperty": {
      "@type": "PropertyValue",
      "name": "DisplaySubscriptionIdentifier",
      "value": "http://www.example.com/local_tv_network/subscription"
  },
  "eligibleRegion":{
    "@type": "GeoShape",
    "@id": "http://example.com/area2",
    "addressCountry": "CA",
    "postalCode": [
      "1A1",
      "K1A"
    ]
  }
}
```

### Example 4

`eligibleRegion` with a `GeoShape` object that
contains a DMA ID:

```
"actionAccessibilityRequirement": {
  "@type": "ActionAccessSpecification",
  "category": "subscription",
  "requiresSubscription": {
    "@type": "MediaSubscription",
    "@id": "http://www.example.com/abcd/subscription",
    "name": "Example Subscription",
    "commonTier": true
  },
  "additionalProperty": {
      "@type": "PropertyValue",
      "name": "DisplaySubscriptionIdentifier",
      "value": "http://www.example.com/abcd/subscription"
  },
  "eligibleRegion":{
    "@type": "GeoShape",
    "@id": "http://example.com/area3",
    "addressCountry": "US",
    "identifier": [
      {
        "@type": "PropertyValue",
        "propertyID": "DMA_ID",
        "value": "501"
      }
    ]
  }
}
```

### Example 5

`eligibleRegion` with a list of `GeoShape` objects.
Each contains a DMA ID:

```
"actionAccessibilityRequirement" : {
   "@type" : "ActionAccessSpecification",
   "eligibleRegion" : [
      {
         "@id" : "http://example.com/dma/601",
         "@type" : "GeoShape",
         "addressCountry" : "US",
         "identifier" : {
            "@type" : "PropertyValue",
            "propertyID" : "DMA_ID",
            "value" : "601"
         }
      },
      {
         "@id" : "http://example.com/dma/602",
         "@type" : "GeoShape",
         "addressCountry" : "US",
         "identifier" : {
            "@type" : "PropertyValue",
            "propertyID" : "DMA_ID",
            "value" : "602"
         }
      }
   ]
}
```

### Example 6

`ineligibleRegion` with blocked-out ZIP codes:

```
"actionAccessibilityRequirement": {
  "@type": "ActionAccessSpecification",
  "category": "subscription",
  "requiresSubscription": {
    "@type": "MediaSubscription",
    "@id": "http://www.example.com/local_tv_network/subscription",
    "name": "Example Subscription",
    "commonTier": true
  },
  "additionalProperty": {
      "@type": "PropertyValue",
      "name": "DisplaySubscriptionIdentifier",
      "value": "http://www.example.com/local_tv_network/subscription"
  },
 "eligibleRegion":   {
      "@type": "Country",
      "name": "US"
    },
  "ineligibleRegion": {
    "@type": "GeoShape",
    "@id": "http://example.com/area1",
    "addressCountry": "US",
    "postalCode": [
      "94118",
      "94119"
    ]
  }
}
```

## Entitlement identifier

The entitlement identifier, `entitlementId`, refers to a string that represents
access to a group of content in your media catalog. To determine whether a user
has access to your content, Google takes the following steps:

1. We make an API call to your [Entitlements endpoint](https://developers.google.com/actions/media/concepts/access-requirements#entitlements-endpoint) to receive the user's entitlement identifiers.
2. We look up the content's required entitlement identifiers from your Media Actions feed.
3. We match a user's `entitlementId` to the [`identifier`](https://developers.google.com/actions/media/reference/data-specification/watch-actions-common-specification#identifier_properties) property of the [media subscription](https://developers.google.com/actions/media/reference/data-specification/watch-actions-common-specification#media_subscription_properties) object in your feed. If at least one `entitlementId` matches, we determine that the user can access the content.

> [!NOTE]
> **Note:** Your service needs to host an [HTTPS endpoint](https://developers.google.com/actions/media/concepts/access-requirements#entitlements-endpoint) that returns a user's entitlement identifiers.

![](https://developers.google.com/static/actions/media/images/image-entitlements-5.png) **Figure 2.** One of the user's entitlement identifiers matches the content's required entitlement identifier.

Google recommends that you use the following syntax for `entitlementId`:

    <domain name> + colon (:) + <access level to content>

Syntax examples:

- `example.com:basic`
- `example.com:premium`
- `example.com:sports`

### Entitlement identifier example

*MediaExampleCompany* 's feed specifies that `Movie XYZ` requires the
`example.com:basic` `entitlementId`, as shown:

```
{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "Movie",
  "@id": "www.example.com/movie_xyz",
  "url": "www.example.com/movie_xyz",
  "name": "Movie XYZ",
  "potentialAction": {
    "@type": "WatchAction",
    "target": [ ... ],
    "actionAccessibilityRequirement": {
      "@type": "ActionAccessSpecification",
      "category": "subscription",
      "requiresSubscription": {
        "@type": "MediaSubscription",
        "@id": "http://www.example.com/basic_subscription",
        "name": "Basic subscription",
        "commonTier": true
        ...
      },
      "additionalProperty": {
        "@type": "PropertyValue",
        "name": "DisplaySubscriptionIdentifier",
        "value": "http://www.example.com/basic_subscription"
      },
      ...
    }
  },
  ...
}
```

## Common access use cases

The following are common access use cases:

- **Free (no login required):** The content is available without login, subscription, or purchase.
- **Free (login required):** The content requires users to be logged in but doesn't require a subscription.
- **Single-tier subscription:** The content requires a subscription. All subscribers can access the same content, whether movies or episodes, regardless of their subscription package.
- **Multi-tier subscription:** The content requires a subscription. Subscribers can access different content, whether movies or episodes, based on their subscription tier. For example, *Silver* versus *Gold*.
- **Add-on subscription:** The content requires a subscription. Subscribers can add premium content on top of their regular subscription.
- **One-time purchase:** The content can be purchased, after which the user can access it indefinitely.
- **Live TV:** A subscription includes access to local, national, and premium channels.
- **Third-party subscription:** The content requires the user to log in with their cable provider.

### Free (no login required)

**No login required**

The content is available without login or subscription.

```
{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "nologinrequired",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    }
  }
}
```

- Set `category` to `nologinrequired`.
- Do not include `expectAcceptanceOf`.

### Free (login required)

**Login required**

The content requires users to be logged in but doesn't require a
subscription.

```
{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "free",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    }
  }
}
```

- Set `category` to `free`.
- Do not include `expectAcceptanceOf`.

### Single-tier subscription

In a single-tiered subscription model, a service provider has one
subscription tier. All subscribers can access the same content, whether
movies or episodes, regardless of their subscription package.

```
{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "subscription",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "requiresSubscription": {
        "@type": "MediaSubscription",
        "name": "Example Package",
        "commonTier": true,
        "@id": "http://www.example.com/example_package"
    },
    "additionalProperty": {
      "@type": "PropertyValue",
      "name": "DisplaySubscriptionIdentifier",
      "value": "http://www.example.com/example_package"
    },
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    }
  }
}
```

### Multi-tier subscription

In a tiered subscription model, a service provider has multiple
subscription tiers, such as *Gold* , *Silver* , and
*Bronze*. Users who have the upper tier subscription can access all
the lower tier content. However, users who have the lower tier
subscription can't access the upper tier content.
![](https://developers.google.com/static/actions/media/images/image-entitlements-2.png) **Figure 3.** A tiered subscription model and its representation of entitlements.

Consider the following scenario:

- Jane subscribes to the *Gold* tier. Your entitlements endpoint returns the following `entitlementId` identifiers:
  - `example.com:bronze`
  - `example.com:silver`
  - `example.com:gold`
- John subscribes to the *Bronze* tier. Your entitlements endpoint returns the following `entitlementId`:
  - `example.com:bronze`
- Your Media Actions feed describes the following requirements:
  - *Movie A* requires `example.com:bronze`.
  - *Movie B* requires `example.com:silver`.

In this scenario, Google determines the following access levels for Jane
and John:

- Both Jane and John have access to *Movie A*.
- Jane has access to *Movie B*, but John doesn't.

```
{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "subscription",
    "requiresSubscription": {
      "@type": "MediaSubscription",
      "@id": "http://www.example.com/basic_subscription",
      "name": "Bronze",
      "commonTier": true
      ...
    },
    "additionalProperty": {
      "@type": "PropertyValue",
      "name": "DisplaySubscriptionIdentifier",
      "value": "http://www.example.com/basic_subscription"
    },
    ...
  }
}
```

### Add-on subscription

In an add-ons subscription model, a service provider allows users to
expand their entitlements and add channels to a base subscription. Users
can add as many channels as they want to.
![](https://developers.google.com/static/actions/media/images/image-entitlements-3.png) **Figure 4.** An add-ons subscription model and its representation of entitlements.

Consider the following scenario:

- Jane has *PRO* and *Sportz* in addition to the *Basic* subscription. Your entitlements endpoint returns the following `entitlementId` identifiers:
  - `example.com:basic`
  - `example.com:pro`
  - `example.com:sportz`
- John only has the *Basic* subscription. Your entitlements endpoint returns the following `entitlementId`:
  - `example.com:basic`
- Your Media Actions feed describes the following requirements:
  - *Movie A* requires `example.com:basic`.
  - *Movie B* requires `example.com:pro`.

In this scenario, Google determines the following access levels for Jane
and John:

- Both Jane and John have access to *Movie A*.
- Jane has access to *Movie B*, but John doesn't.

```
{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "subscription",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    }
    "requiresSubscription": [
      {
          "@type": "MediaSubscription",
          "@id": "https://www.example.com/package/basic",
          "name": "Basic",
          "sameAs": "https://www.example.com/package/basic",
          "commonTier": true
        },
        {
          "@type": "MediaSubscription",
          "@id": "https://www.example.com/packages/basic/pro",
          "name": "PRO",
          "sameAs": "https://www.example.com/package/pro",
          "identifier": "example.com:pro",
          "commonTier": false
        },
        {
          "@type": "MediaSubscription",
          "@id": "https://www.example.com/package/sportz",
          "name": "Sportz",
          "sameAs": "https://www.example.com/package/sports",
          "identifier": "example.com:sportz",
          "commonTier": false
        }
    ],
      "additionalProperty": {
        "@type": "PropertyValue",
        "name": "DisplaySubscriptionIdentifier",
        "value": "http://www.example.com/package/basic"
      },
    }
  }
}
```

### One-time purchase

**Purchase**

The content is available for an indefinite amount of time after the
purchase.

```
{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "purchase",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    },
    "expectsAcceptanceOf": {
      "@type": "Offer",
      "price": 7.99,
      "priceCurrency": "USD",
      "seller": {
        "@type": "Organization",
        "name": "Example",
        "sameAs": "http://www.example.com/"
      }
    }
  }
}
```

- Set `category` to `purchase`.
- Include `expectAcceptanceOf` in `actionAccessibilityRequirement` to indicate the price of the purchase.

*** ** * ** ***

**Rental**

The content is available for a finite amount of time after the
purchase.

```
{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "rental",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    },
    "expectsAcceptanceOf": {
      "@type": "Offer",
      "price": 7.99,
      "priceCurrency": "USD",
      "seller": {
        "@type": "Organization",
        "name": "Example",
        "sameAs": "http://www.example.com/"
      }
    }
  }
}
```

- Set `category` to `rental`.
- Include `expectAcceptanceOf` in `actionAccessibilityRequirement` to indicate the price of the rental.

### Live TV

In a Media Actions feed, you can restrict access to a Live TV
[channel](https://developers.google.com/actions/media/concepts/live-tv-channel) or
[event](https://developers.google.com/actions/media/concepts/live-tv-event) based on the
following two user conditions:

- [The user's device location](https://developers.google.com/actions/media/concepts/access-requirements#geographic-area)

  To restrict access to the TV channel, specify the area where users
  have access to it. This condition usually applies to local broadcast
  TV channels.
- [The user's account status](https://developers.google.com/actions/media/concepts/access-requirements#entitlement-identifier)

  If access to a TV channel depends on a user's account-level setting,
  use
  [entitlement identifiers](https://developers.google.com/actions/media/concepts/access-requirements#entitlement-identifier) to
  represent the restriction.

  This condition usually applies to the following use-cases:
  - **Bundle:** National channels are often included in bundles, and users choose which bundle they want to subscribe to.
  - **Add-on:** Some premium channels require users to selectively add extra channels to their subscription.
  - **Regional Sports Network (RSN):** RSNs are usually associated with a user's "home" location. Users can watch content on the RSN even when they travel outside of their "home" location.

### Third-party subscription

**Third-party subscription**

The content is available to the subscribers from a different service.

```
{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "externalsubscription"
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "requiresSubscription":{
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/faq",
      "name": "Example",
      "sameAs": "https://www.example.com/faq",
      "authenticator": {
        "@type": "Organization",
        "name": "TVE"
      }
    },
    "additionalProperty": {
      "@type": "PropertyValue",
      "name": "DisplaySubscriptionIdentifier",
      "value": "http://www.example.com/faq"
     },
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    }
  }
}
```

- Add `authenticator` to indicate that a different service authenticates the subscribers. For example, HBO GO requires a subscription from the cable provider.

## Common tier packages

Common tier content is available to all subscribers regardless of their
subscription package. The common tier applies to all content with the `category`
of `subscription`. For more information on the `category` property, check the
[Paywall type](https://developers.google.com/actions/media/concepts/access-requirements#paywall-type) section.

> [!NOTE]
> **Note:** The common tier doesn't have to correspond to a package that a user can actually purchase.

### Why is a common tier package required?

Multiple Google surfaces provide TV \& movie recommendations to users. To set
user expectations about cost, Google must understand what content is available
to all subscribers through use of the common tier. Google must also understand
what content is available to subscribers with specific subscription packages.

Google recommends titles available on the common tier unless you support the
[entitlement API](https://developers.google.com/actions/media/concepts/access-requirements#entitlements-endpoint).
The API lets Google understand the non-common-tier titles each specific
user can access.

### When should I create a common tier package?

A common tier package is required when your service offers content that's
available to all subscribers. This includes services that offer only one package
and services that offer multiple packages or add-ons.

Providers that have no content available to all subscribers don't need to create
a common tier package. An example is service providers that provide mutually exclusive
content across all of their packages.

### Common tier examples

The following are examples of the common tier.

#### Tiered Subscription

In a tiered subscription model, a service provider has multiple subscription
tiers, such as **Gold** , **Silver** , and **Bronze** tiers. Users with the
upper-tier subscription have access to all the content in the lower tiers. Users
with the lower-tier subscription don't have access to the content in the upper
tier. The following image is an example of the package structure.
![The Gold tier contains all of the content of the Silver tier, which
itself contains all of the Bronze tier.](https://developers.google.com/static/actions/media/images/tieredsub.png) **Figure 5.** Tiered subscription package structure.

In the following code example, the bronze package is the common tier because all
users have access to all content in that tier.

```
"requiresSubscription": [
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/bronze",
      "name": "Bronze",
      "sameAs": "https://www.example.com/package/bronze",
      "commonTier": true
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/silver",
      "name": "Silver",
      "sameAs": "https://www.example.com/package/silver",
      "identifier": "example.com:silver",
      "commonTier": false
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/gold",
      "name": "Gold",
      "sameAs": "https://www.example.com/package/gold",
      "identifier": "example.com:gold",
      "commonTier": false
    }
  ],
```

#### Add ons

In an add-ons subscription model, a service provider allows users to expand
their entitlements and add channels to a basic subscription. Users can add as
many channels as they want. The following image is an example of the package
structure.
![Every user starts with the Basic channel, and they can choose to add
any combination of the PRO, Sportz, and Moviemax channels.](https://developers.google.com/static/actions/media/images/addonssub.png) **Figure 6.** Add-ons subscription package structure.

If you have a channel available to all users and there's no cost for the
channel, you can merge the package with the common tier package.

In the following code example, the basic package is the common tier because all
users have access to all content in this package.

```
"requiresSubscription": [
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/basic",
      "name": "Basic",
      "sameAs": "https://www.example.com/package/basic",
      "commonTier": true
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/packages/basic/pro",
      "name": "PRO",
      "sameAs": "https://www.example.com/package/pro",
      "identifier": "example.com:pro",
      "commonTier": false
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/sportz",
      "name": "Sportz",
      "sameAs": "https://www.example.com/package/sports",
      "identifier": "example.com:sportz",
      "commonTier": false
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/moviemax",
      "name": "Moviemax",
      "sameAs": "https://www.example.com/package/moviemax",
      "identifier": "example.com:moviemax",
      "commonTier": false
    }
  ],
```

#### Packages with content that intersects

In a content model where packages have content that intersects, a service
provider sells packages that include some content from other packages. The
following image is an example of the package structure.
![A Venn diagram where the overlap between Packages 1, 2, and 3 is
labeled 'Common Tier'.](https://developers.google.com/static/actions/media/images/intersect.png) **Figure 7.** Package structure with intersecting content.

In the following code example, the provider offers three packages where some
content intersects across all of the packages. In this case, a fourth package
that represents the common tier is required. It must include all content
available across all three packages.

```
"requiresSubscription": [
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/1",
      "name": "Package 1",
      "sameAs": "https://www.example.com/package/1",
      "identifier": "example.com:package1",
      "commonTier": false
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/2",
      "name": "Package 2",
      "sameAs": "https://www.example.com/package/2",
      "identifier": "example.com:package2",
      "commonTier": false
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/3",
      "name": "Package 3",
      "sameAs": "https://www.example.com/package/3",
      "identifier": "example.com:package3",
      "commonTier": false
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/common",
      "name": "Common Tier Package",
      "sameAs": "https://www.example.com/package/common",
      "commonTier": true
    }
  ],
```

#### Packages without content that intersects

In a content model where all of the content packages don't intersect, a service
provider sells packages that include no content from other packages. The
following image is an example of the package structure.
![Packages 1, 2 and 3 are completely separate.](https://developers.google.com/static/actions/media/images/nointersect.png) **Figure 8.** Package structure with no intersecting content.

In the following example, the provider offers three packages with no content
intersecting across all of the packages. No common tier package is required.

> [!NOTE]
> **Note:** For non-common tier packages, be sure to set the \`commonTier\` property to \`false\`.

```
"requiresSubscription": [
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/1",
      "name": "Package 1",
      "sameAs": "https://www.example.com/package/1",
      "identifier": "example.com:package1",
      "commonTier": false
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/2",
      "name": "Package 2",
      "sameAs": "https://www.example.com/package/2",
      "identifier": "example.com:package2",
      "commonTier": false
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/3",
      "name": "Package 3",
      "sameAs": "https://www.example.com/package/3",
      "identifier": "example.com:package3",
      "commonTier": false
    }
  ],
```

> [!NOTE]
> **Note:** You can use the **additionalProperty** schema to inform Google of which package you would like displayed.

## Entitlements endpoint

Use the information from this section to host an HTTPS endpoint that returns the
entitlements associated with a user.

### Prerequisite

Before you begin, verify that your service supports the
[OAuth 2.0 flow](https://developers.google.com/actions/identity/oauth2) with Google.

### Request

To receive a user's entitlements, Google sends a request that contains the
user's OAuth token. Your endpoint needs to identify the user based on that OAuth
token. See the following example:

    GET /resource HTTP/1.1
    Host: server.example.com
    Authorization: Bearer <OAuthToken>

### Response

Your endpoint needs to return a response with the following properties:

| Property ||
|---|---|
| `subscription` | **Required** This is a field inside the root response. |
| `subscription.type` | **Required** This property can have the following values: - `ActiveSubscription`: The user has an active subscription to the provider. - `ActiveTrial`: The user has an active trial for the provider. - `InactiveSubscription`: The user doesn't have an active subscription or an active trial. |
| `subscription.expiration_date` | **Optional** The expiration date of this entitlement, in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601), which includes the timezone. For more details, see [Expiration dates](https://developers.google.com/actions/media/concepts/access-requirements#expiration-dates). |
| `entitlements` | **Optional** This a root property contains the `entitlementId` values that the user holds. |
| `entitlements.entitlement` | **Required** if access to your streaming catalog varies based on the type of subscription. This property contains the `entitlementId`. For more information, see [Entitlement identifier](https://developers.google.com/actions/media/concepts/access-requirements#entitlement-identifier). |
| `entitlements.expiration_date` | **Optional** The expiration date of this subscription, in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601), which includes the timezone. For more details, see [Expiration dates](https://developers.google.com/actions/media/concepts/access-requirements#expiration-dates). |

#### Expiration dates

There are two properties in an endpoint response that deal with expiration
dates: `subscription.expiration_date` and `entitlements.expiration_date`. You
can include one of them or neither, but not both. Which one you use depends on
your subscription model.

| Subscription model ||
|---|---|
| Access to your streaming catalog is the same for all subscribers. | Because you don't need to specify the `entitlements` property, specify `subscription.expiration_date`. |
| Access to your streaming catalog varies based on the details of a user's subscription. | If your subscription model has multiple tiers or add-ons that expire over time, do one of the following: - If all the `entitlements.entitlement` values expire at the same time, specify `subscription.expiration_date`. - If some `entitlements.entitlement` values expire at different times, specify `entitlements.expiration_date`. |

#### Example responses

The following are example responses of different subscription states:

- Active subscription
- Active subscription with an expiration date
- No subscription
- Active subscriptions to multiple tiers or add-ons

### Active subscription

**Active subscription**

A user has an active subscription to *example.com*. In this
case, all subscribers have access to your entire streaming catalog
regardless of their subscription type.

```
{
  "subscription" : {
    "type": "ActiveSubscription",
  }
}
```

### Active subscription with an expiration date

**Active subscription with an expiration date**

A user has an active subscription to *example.com*, and the
subscription has an expiration date. In this case, all subscribers have
access to your entire streaming catalog regardless of their subscription
type.

```
{
  "subscription" : {
    "type": "ActiveSubscription",
    "expiration_date": "2019-11-10T10:00:00Z"
  }
}
```

### No subscription

**No subscription**

A user has no subscription to *example.com*.

```
{
  "subscription" : {
    "type": "InactiveSubscription"
  }
}
```

### Active subscriptions to multiple tiers or add-ons

**Active subscriptions to multiple tiers or add-ons**

A user has a subscription to `example.com:premium` until a certain date.

```
{
  "subscription" : {
    "type": "ActiveSubscription",
  }
  "entitlements": [
    {
      "entitlement": "example.com:premium",
      "expiration": "2019-11-10T10:00:00Z"
    }
  ]
}
```

> [!NOTE]
> **Note:** If the user from a request doesn't exist, your endpoint needs to return a `404` error. Furthermore, an empty response from your endpoint is considered invalid and is ignored.

### Rate limit

Google refreshes a user's entitlements information up to every six hours. To
smooth out the maximum queries per second (QPS), Google distributes the queries
to your endpoint evenly over time. Thus, you can estimate the expected average
QPS for your endpoint with the following formula:

Expected average QPS = *\<total number of users\>*
/ 21,600 seconds (6 hours x 60 minutes x 60 seconds)

If you support a large number of users, Google can adjust the 6-hour interval.
If necessary, contact Google to discuss the configuration.

### Contact Google

When your endpoint is ready, contact Google to inform the endpoint's URL.

## Action access specification properties

See the
[action access specification properties](https://developers.google.com/actions/media/reference/data-specification/watch-actions-common-specification#action_access_specification_properties) section for reference
information.