## GetReader

`GetReader` allows for a publisher to validate if one of their readers with a
known PPID has linked their subscription to Google. Using a `GET` request,
the publisher queries for a PPID belonging to a particular Publication ID.

### Request

REST API: `GET` request

    https://readerrevenuesubscriptionlinking.googleapis.com/v1/publications/publicationId/readers/ppid

Client library (Node.js)

    async function getReader(ppid) {
      const publicationId = process.env.PUBLICATION_ID;
      return await client.publications.readers.get({
        name: `publications/${publicationId}/readers/${ppid}`,
      });
    };

### Response

The endpoint will return either a 200 with a JSON body containing the
`created_time` of the linked subscription, or an error if no PPID is found
for the publication. See [the errors section](https://developers.google.com/news/subscription-linking/api/error-handling) for more
information.

    {
      "name": "publications/CAowqfCKCw/readers/22553",
      "createTime": "2025-07-30T18:26:58.050224Z",
      "publicationId": "CAowqfCKCw",
      "ppid": "22553",
      "originatingPublicationId": "CAowqfCKCw"
    }

## GetReaderEntitlements

`GetReaderEntitlements` allows a publisher to query for entitlements for a PPID
that the publisher previously provided. Using a GET request, the publisher
requests the entitlements by providing a PPID and Publication ID.

### Request

REST API: `GET` request

    https://readerrevenuesubscriptionlinking.googleapis.com/v1/publications/publicationId/readers/ppid/entitlements

Client library (Node.js)

    async function getReaderEntitlements(ppid) {
      const publicationId = process.env.PUBLICATION_ID;
      return await client.publications.readers.getEntitlements({
        name: `publications/${publicationId}/readers/${ppid}/entitlements`
      });
    };

### Response

For a successful request, the return format is identical to the format used to
store entitlements with the
[`UpdateReaderEntitlements`](https://developers.google.com/news/subscription-linking/api/methods#updatereaderentitlements) `PATCH` request.

    {
      "name": "publications/dailybugle.com/readers/6789/entitlements",
      "entitlements": [
          {
            "product_id": "dailybugle.com:basic",
            "subscription_token": "dnabhdufbwinkjanvejskenfw",
            "detail": "This is our basic plan",
            "expire_time": "2022-08-19T04:53:40+00:00"
          },
          {
            "product_id": "dailybugle.com:premium",
            "subscription_token": "wfwhddgdgnkhngfw",
            "detail": "This is our premium plan",
            "expire_time": "2022-07-19T04:53:40+00:00"
          },
          {
            "product_id": "dailybugle.com:deluxe",
            "subscription_token": "fefcbwinkjanvejfefw",
            "detail": "This is our deluxe plan",
            "expire_time": "2022-08-20T04:53:40+00:00"
          }
      ]
    }

For users who don't have entitlements, but do have a linked PPID (for example,
an entitlement that has expired and been purged), an entitlements request will
return an empty entitlements array as part of the standard entitlements object.

    {
      "name": "publications/dailybugle.com/readers/6789/entitlements"
    }

## UpdateReaderEntitlements

`UpdateReaderEntitlements` is used for creating and updating entitlements for a
reader, based on their PPID.

This sample payload grants the reader with PPID `6789` entitlements to three
Product IDs for The Daily Bugle: `dailybugle.com:basic`,
`dailybugle.com:premium`, and `dailybugle.com:deluxe`. When reader `6789`
subsequently uses Google surfaces for Search and Discover, the
"From your subscriptions" list will feature any relevant results
from dailybugle.com articles tagged with any of these Product IDs.

> [!NOTE]
> **Note:** This method is used for both creating the initial entitlements for a = reader, as well as updating them.

### Request

REST API: `PATCH` request

    https://readerrevenuesubscriptionlinking.googleapis.com/v1/publications/publicationId/readers/ppid/entitlements

Request body: For more information about the `entitlements` object, refer to the
[glossary](https://developers.google.com/news/subscription-linking/appendix/glossary#entitlements_object)
page.

    {
      entitlements : [{
        product_id: `${publicationId}:basic`,
        subscription_token: 'abc1234',
        detail: 'This is our basic plan',
        expire_time: '2025-10-21T03:05:08.200564Z'
      }]
    }

Client library (Node.js)

    async function updateReaderEntitlements(ppid) {
      const publicationId = process.env.PUBLICATION_ID;
      const requestBody = {
        entitlements : [{
          product_id: `${publicationId}:basic`,
          subscription_token: 'abc1234',
          detail: 'This is our basic plan',
          expire_time: '2025-10-21T03:05:08.200564Z'
        }]
      };
      return await client.publications.readers.updateEntitlements({
        name: `publications/${publicationId}/readers/${ppid}/entitlements`,
        requestBody
      });
    }

### Response

Upon a successful PATCH operation, the saved `entitlements` object will be
returned, in the same format as [`GetReaderEntitlements`](https://developers.google.com/news/subscription-linking/api/methods#getreaderentitlements).

## DeleteReader

`DeleteReader` allows for a publisher to manually delete a linked subscription.
Using a `DELETE` request, the publisher submits a PPID for a Publication ID to
be deleted.

Before calling `DeleteReader`, you must either delete entitlements
first using `UpdateReaderEntitlements` with an empty array
(`{ "entitlements": [] }`), or set the optional `force` parameter to `true` if
you need to delete a reader that has entitlements.
The `force` parameter defaults to `false`.

### Request

REST API: `DELETE` request

    https://readerrevenuesubscriptionlinking.googleapis.com/v1/publications/publicationId/readers/ppid?force={boolean}

Client library (Node.js)

    async function deleteReader(ppid, forceDelete = false) {
      const publicationId = process.env.PUBLICATION_ID;
      return await client.publications.readers.delete({
        name: `publications/${publicationId}/readers/${ppid}`,
        force: forceDelete
      });
    }

### Response

A successful delete returns a 200 with an empty JSON object `{}`.

    {}