Stay organized with collections
Save and categorize content based on your preferences.
The information in this document can help troubleshoot issues that you might
encounter while you implement Subscription Linking.
Subscription Linking CTA stuck on loading screen
Error example:
Figure 1. Subscription Linking CTA doesn't load.
To resolve this issue, check the following:
Make sure that you add the origins of the pages, including testing
subdomains, as
additional URLs
in the publication settings of Publisher Center.
Make sure the status of the URL is "Verified" instead of "Verify".
For Extended Access or Reader Revenue Manager Enterprise implementations,
make sure that you add the origins of the pages, including testing
subdomains, to the
authorized JavaScript origins
of the OAuth 2.0 Client you configured for such implementation. This needs
to be done in Google Cloud Console.
Account couldn't be linked
Error example:
Figure 2. Account couldn't be linked issue.
To resolve this issue, check the following:
Make sure to accept the Terms of Service for Subscription Linking in the
Publisher Center. To do so, go to the Subscription Linking settings
and click sign the subscription linking terms of service.
If the Google Account has already been linked, you'll get an error message
when you reattempt to link the subscription. You must unlink the
subscription, through the subscriptions
page in Google Account, before
you repeat the client-side integration test.
Permissions error when calling the Subscription Linking API
Error example:
Code
403
Message
'readerrevenuesubscriptionlinking.readerEntitlements.update'
denied on resource '//readerrevenuesubscriptionlinking.googleapis.com/publications/example.com/readers/10078823/entitlements' (or it may not exist)."
To resolve this issue, check the following:
Make sure that you use the same project as specified in the
Subscription Linking setup.
When you set up Subscription Linking in the Publisher Center, use the
Project number.
You can locate the Project number from your project dashboard.
In the project Identity and Access Management (IAM), make sure that the
service account is granted with the role
as Subscription Linking Admin. Note that the role change propagation
through the system might take time. If you receive a 403 error when making
API calls, even after you confirm that your service account has the correct
IAM role, wait for a few moments and then try your request again.
If you are unsure which service accounts to use or whether they've the
necessary IAM role, use the
Policy Analyzer
from the project that you set up for Subscription Linking. Create and run a
custom query with the following query parameters:
Parameter 1
Role
Role
Subscription Linking Admin
Make sure that you use the correct service account key when you call the
Subscription Linking API. Inspect the following properties in your service
account key (JSON file):
type: It must be service_account.
project_id: It must be the Project ID of the Project number
specified in the Subscription Linking setup.
client_email: It must be the same service account in project IAM
that's assigned with the role Subscription Linking Admin.
If you obtained the access token through Google OAuth 2.0 token endpoint
(https://oauth2.googleapis.com/token), make sure that the token is valid and
not expired when you call Subscription Linking APIs. If the token expires,
you have to obtain a new one.
If you use the REST API, make sure that you use the Publication ID you
provided in the Subscription Linking setup. For example, if your
Publication ID is example.com, then the request URL must contain it.
✅ Use only the configured Publication ID:
publications/example.com/readers/10078823/entitlements
❌ Don't use Publication ID other than the one specified in
Subscription Linking configuration:
publications/example-staging.com/readers/10078823/entitlements
❌ Don't include the publication product in the request:
publications/example.com:premium/readers/10078823/entitlements
Invalid argument error when updating the entitlement
Error example:
Message
Error: Request contains an invalid argument
To resolve this issue, check the following:
Make sure that you provide the entitlements object in the correct format.
See this
example.
Make sure that product_id is in the format of publication_id:product.
✅ Valid example: "product_id":"example.com:basic"
❌ Invalid example: "product_id":"example.com"
Not seeing articles highlighted in the search results
Make sure that you put a valid productID in the structured data that
corresponds to a set of Product IDs you use to update reader's
entitlement.
Use a rich result report
for "subscribed content" in Search Console to see any issues related
to your structured data.
Cannot change the Subscription Linking call to action message language
The Subscription Linking call to action language is determined
by the user's settings. It cannot be globally overridden.
The language is determined as follows:
If the user is logged in with their Google Account, the primary language set in their Google Account settings (https://myaccount.google.com/language) is used.
If the user is not logged in, the language is based on either their browser's or operating system's primary language setting.
Subscription Linking call to actions don't support all languages.
If a user's primary language is not supported, the call to action may default
to English.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-27 UTC."],[[["\u003cp\u003eThis document provides troubleshooting steps for common issues encountered during Subscription Linking implementation, including problems with the loading prompt, account linking, API permissions, and search result visibility.\u003c/p\u003e\n"],["\u003cp\u003eEnsure that page origins and testing subdomains are correctly added as additional URLs in the Publisher Center and as authorized JavaScript origins in the Google Cloud Console for proper functionality.\u003c/p\u003e\n"],["\u003cp\u003eVerify the acceptance of the Terms of Service for Subscription Linking within the Publisher Center, and manage linked subscriptions through the user's Google Account subscriptions page if necessary.\u003c/p\u003e\n"],["\u003cp\u003eConfirm the correct project setup, enabled API, appropriate IAM roles for the service account, and valid service account key details to resolve permissions errors when utilizing the Subscription Linking API.\u003c/p\u003e\n"],["\u003cp\u003eTo ensure articles are highlighted correctly in search results, you must add structured data to all articles, and make sure that the product IDs are correct and correspond to the ones used when updating the reader's entitlements.\u003c/p\u003e\n"]]],[],null,["The information in this document can help troubleshoot issues that you might\nencounter while you implement **Subscription Linking**.\n| **Tip:** Open the JavaScript console and look for error messages from the `swg.js` client library. This can help you identify potential issues in your implementation.\n\nSubscription Linking CTA stuck on loading screen\n\nError example:\n\n**Figure 1.** Subscription Linking CTA doesn't load.\n\nTo resolve this issue, check the following:\n\n- Make sure that you add the origins of the pages, including testing subdomains, as [additional URLs](https://support.google.com/news/publisher-center/answer/13543753) in the publication settings of Publisher Center.\n - Make sure the status of the URL is \"Verified\" instead of \"Verify\".\n- For Extended Access or Reader Revenue Manager Enterprise implementations, make sure that you add the origins of the pages, including testing subdomains, to the [authorized JavaScript origins](https://support.google.com/cloud/answer/6158849#zippy=%2Cauthorized-domains) of the OAuth 2.0 Client you configured for such implementation. This needs to be done in Google Cloud Console.\n\n| **Note:** If you've recently added the origins, it can take up to an hour before such origins can access the `swg.js` client library.\n\nAccount couldn't be linked\n\nError example:\n\n**Figure 2.** Account couldn't be linked issue.\n\nTo resolve this issue, check the following:\n\n- Make sure to accept the **Terms of Service for Subscription Linking** in the **Publisher Center** . To do so, go to the **Subscription Linking** settings and click **sign the subscription linking terms of service**.\n- If the Google Account has already been linked, you'll get an error message when you reattempt to link the subscription. You must unlink the subscription, through the [subscriptions\n page](https://myaccount.google.com/subscriptions) in Google Account, before you repeat the client-side integration test.\n\nPermissions error when calling the Subscription Linking API\n\nError example:\n\n|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Code | `403` |\n| Message | `'readerrevenuesubscriptionlinking.readerEntitlements.update'` denied on resource `'//readerrevenuesubscriptionlinking.googleapis.com/publications/example.com/readers/10078823/entitlements'` (or it may not exist).\" |\n\nTo resolve this issue, check the following:\n\n- Make sure that you use the same project as specified in the [Subscription Linking setup](https://support.google.com/news/publisher-center/answer/13543753). When you set up Subscription Linking in the Publisher Center, use the [**Project number**](https://cloud.google.com/resource-manager/docs/creating-managing-projects). You can locate the **Project number** from your [project dashboard](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects).\n- Make sure that [Subscription Linking API](https://console.cloud.google.com/apis/library/readerrevenuesubscriptionlinking.googleapis.com) is enabled in your project.\n- In the project Identity and Access Management (IAM), make sure that the service account is [granted with the role](/news/subscribe/subscription-linking/implementation/server-side) as **Subscription Linking Admin**. Note that the role change propagation through the system might take time. If you receive a 403 error when making API calls, even after you confirm that your service account has the correct IAM role, wait for a few moments and then try your request again.\n- If you are unsure which service accounts to use or whether they've the\n necessary IAM role, use the\n [Policy Analyzer](https://cloud.google.com/policy-intelligence/docs/analyze-iam-policies#principal-query-all)\n from the project that you set up for Subscription Linking. Create and run a\n custom query with the following query parameters:\n\n | Parameter 1 | Role |\n |-------------|----------------------------|\n | Role | Subscription Linking Admin |\n\n- Make sure that you use the correct service account key when you call the\n Subscription Linking API. Inspect the following properties in your service\n account key (JSON file):\n\n - **type:** It must be service_account.\n - **project_id:** It must be the **Project ID** of the **Project number** specified in the Subscription Linking setup. **Note:** **Project ID** and **Project number** are two different identifiers that you can locate from your [project dashboard](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects).\n - **client_email:** It must be the same service account in project IAM that's assigned with the role **Subscription Linking Admin**.\n- If you obtained the access token through Google OAuth 2.0 token endpoint\n (https://oauth2.googleapis.com/token), make sure that the token is valid and\n not expired when you call Subscription Linking APIs. If the token expires,\n you have to obtain a new one.\n\n- If you use the REST API, make sure that you use the **Publication ID** you\n provided in the **Subscription Linking** setup. For example, if your\n Publication ID is `example.com`, then the request URL must contain it.\n\n - ✅ Use only the configured Publication ID: `publications/example.com/readers/10078823/entitlements`\n - ❌ Don't use Publication ID other than the one specified in **Subscription Linking** configuration: `publications/example-staging.com/readers/10078823/entitlements`\n - ❌ Don't include the publication product in the request: `publications/example.com:premium/readers/10078823/entitlements`\n\n| **Note:** It might take several minutes or longer for the permission change in IAM to take effect. For more information, see [Access change propagation](https://cloud.google.com/iam/docs/access-change-propagation).\n\nInvalid argument error when updating the entitlement\n\nError example:\n\n|---------|---------------------------------------------|\n| Message | Error: Request contains an invalid argument |\n\nTo resolve this issue, check the following:\n\n- Make sure that you provide the `entitlements` object in the correct format. See this [example](/news/subscribe/subscription-linking/api/methods#request_3).\n- Make sure that `product_id` is in the format of `publication_id:product`.\n - ✅ Valid example: `\"product_id\":\"example.com:basic\"`\n - ❌ Invalid example: `\"product_id\":\"example.com\"`\n\nNot seeing articles highlighted in the search results\n\nTo resolve this issue, check the following:\n\n- Make sure to add the [structured data](/news/subscribe/subscription-linking/implementation/structured-data) to all your articles. Use the [Rich Results\n Test](https://search.google.com/test/rich-results) to validate your structured data.\n- Make sure that you put a valid `productID` in the structured data that corresponds to a set of Product IDs you use to [update reader's\n entitlement](/news/subscribe/subscription-linking/api/methods#updatereaderentitlements).\n- Use a [rich result report](https://support.google.com/webmasters/answer/7552505) for \"subscribed content\" in **Search Console** to see any issues related to your structured data.\n\n| **Note:** There are ranking factors involved when we display the **From Your\n| Subscriptions** feature. This means it isn't always guaranteed that you see your news article for any given search term.\n\nCannot change the Subscription Linking call to action message language\n\nThe Subscription Linking call to action language is determined\nby the user's settings. It cannot be globally overridden.\n\nThe language is determined as follows:\n\n1. If the user is logged in with their Google Account, the primary language set in their Google Account settings (\u003chttps://myaccount.google.com/language\u003e) is used.\n\n2. If the user is not logged in, the language is based on either their browser's or operating system's primary language setting.\n\nSubscription Linking call to actions don't support all languages.\nIf a user's primary language is not supported, the call to action may default\nto English."]]
