API methods

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 for more information.

{
  "name": "publications/gtech-demo.appspot.com/readers/81112",  
  "create_time": "2022-04-19T04:53:40+00:00"
}

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 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",
  "createTime": "2023-02-07T17:38:57.425577Z"
}

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.

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 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.

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 {}.

{}