canonical: https://jentic.com/apis/googleapis.com/reader-revenue-subscription-linking # Google Reader Revenue Subscription Linking API The Reader Revenue Subscription Linking API lets news publishers tie a Google reader identity to a publisher subscription so that signed-in Google users see their entitlements honored across Google surfaces. Publishers exchange reader IDs and subscription metadata with Google to mark a reader as entitled, update existing entitlements, or remove the link when a subscription ends. The API is the connective tissue between a publisher's subscription system of record and Google's reader-facing surfaces. ## For AI agents Link, update, and unlink Google reader identities with publisher subscriptions so reader entitlements are recognized across Google surfaces. ## Scope Does not process payments, run paywalls, or send subscriber email - use only to link, update, and unlink Google reader identities with publisher subscription records. ## Capabilities - Create or update a reader-to-subscription link with the publisher's entitlement metadata - Retrieve the current subscription link for a Google reader identity - Delete a reader-subscription link when a reader cancels or unsubscribes - Synchronize entitlement state from a publisher's subscription system of record into Google - Honor reader entitlements consistently across Google reader-facing surfaces - Drive subscription linking from webhook handlers when subscriptions change ## Use cases ### Initial Reader Onboarding When a reader signs in to a publisher's site with their Google account and their subscription is verified, the publisher calls Subscription Linking to register the entitlement with Google. From then on, the reader's entitlement is honored on Google reader surfaces. Example prompt: Call PATCH /v1/publications/{publication}/readers/{reader_id} with subscription metadata when a verified reader signs in for the first time. ### Subscription Lifecycle Sync Publishers run their subscription system of record (Stripe, Recurly, Zuora, in-house) and need entitlement changes there to flow to Google. Webhook handlers on the publisher side translate billing events into Subscription Linking API calls so Google's view of the entitlement always matches the source of truth. Example prompt: When the billing system fires a subscription.updated webhook, look up the linked Google reader and call the upsert endpoint with the new plan tier and renewal date. ### Cancellation and Unlink When a reader cancels or their subscription lapses, the publisher must remove the entitlement link so Google does not continue to show the reader as entitled. Subscription Linking exposes a delete operation that performs this unlink cleanly. Example prompt: When a reader cancels, call DELETE /v1/publications/{publication}/readers/{reader_id} to remove the entitlement from Google. ### Agent-Driven Entitlement Reconciliation An agent monitors the publisher's billing data and reconciles entitlement state with Google through Jentic, calling the Subscription Linking API to add, update, or remove links so the Google view of who is entitled stays in sync with the publisher's system of record. Example prompt: Search Jentic for link a google reader to a subscription, load the schema for the readers upsert operation, and execute it for the affected reader. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /v1/{+name} | Retrieve a reader-subscription link | | PATCH | /v1/{+name} | Create or update a reader-subscription link | | DELETE | /v1/{+name} | Delete a reader-subscription link | ## Key resources - **publications** — The publisher's publication identifier under which readers are managed - **readers** — Per-Google-reader subscription link state with create, get, and delete operations ## Why Jentic - **Setup:** Wiring the Reader Revenue Subscription Linking API by hand means setting up publisher Google OAuth 2.0, refreshing scoped access tokens, and formatting reader resource names for the three endpoints on readerrevenuesubscriptionlinking.googleapis.com. Through Jentic you install once, import the Reader Revenue Subscription Linking API from the API Directory, store the OAuth credential once, and your agent calls it. - **Permission scoping:** This API puts the reader in the URL path (/v1/{+name}), so a rule can pin your agent to one publication's reader records: it can read entitlements for that scope and nothing else. You choose the operations it may call, so state-changing ones like updating or unlinking a reader are not included unless you add them. - **Credential handling:** Your publisher Google OAuth credential is stored once, encrypted, by your own Jentic One instance and a scoped access token is injected at execution time. The credential never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'link a reader' or 'get a reader entitlement', and Jentic returns the matching Subscription Linking operation with its input schema so the agent calls the right endpoint without interpreting the discovery doc for a three-endpoint API. ## Related APIs - **Gmail API** — Sends transactional subscription emails to readers - **AdSense Management API** — Manages the publisher's ad inventory alongside reader subscriptions - **AdMob API** — Mobile ad management for publishers running app surfaces alongside reader sites ## FAQ ### What authentication does the Reader Revenue Subscription Linking API use? The API uses Google OAuth 2.0 with publisher-scoped credentials issued through the Reader Revenue Manager onboarding. Through Jentic the OAuth credentials live encrypted in the vault and short-lived access tokens are injected at call time so the refresh token never enters the agent context. ### Does this API process payments or charge subscribers? No, billing stays with the publisher's existing system. This API only links a Google reader identity to a subscription record so Google can recognize the entitlement on Google surfaces. ### What are the rate limits for the API? The API exposes three operations and is intended for event-driven calls in response to subscription lifecycle changes. Rate limits are documented by the Reader Revenue Manager team and are sized for normal subscriber-event throughput, not for full-base reconciliation sweeps in tight loops. ### How do I unlink a reader through Jentic? Search Jentic for unlink a google reader from a subscription, load the schema for the readers delete operation which maps to DELETE /v1/{+name} on a reader resource, and execute it with the reader's resource name when the subscription is cancelled. ### Is the Reader Revenue Subscription Linking API free? API access is included with Reader Revenue Manager onboarding for eligible publishers and is not separately metered. Eligibility and onboarding details are documented on the Reader Revenue Manager publisher site. ### How do I update an entitlement when a reader changes plan? Call the upsert operation on the reader resource with the new plan tier, renewal date, and any other entitlement metadata; the API replaces the prior link in place rather than requiring a delete-then-create. ### Can I limit what my agent is allowed to do with the Reader Revenue Subscription Linking API? Yes. Because you run Jentic One yourself, your own rules decide which of the three operations your agent may call and which publisher OAuth credential it uses. Since this API puts the reader in the URL path (/v1/{+name}), a rule can pin the agent to one publication's reader records, and you can allow only the read (GET) operation while withholding the state-changing PATCH upsert and DELETE unlink operations unless you explicitly grant them. The scoped access token is injected at call time, so the agent can act on entitlements only within the boundaries you set.