Change subscription types

After you create a subscription, you can change the delivery method to push,pull, or export.

Before you begin

Required roles and permissions

To get the permissions that you need to change subscription types and manage them, ask your administrator to grant you thePub/Sub Editor (roles/pubsub.editor) IAM role on your topic or project. For more information about granting roles, seeManage access to projects, folders, and organizations.

This predefined role contains the permissions required to change subscription types and manage them. To see the exact permissions that are required, expand theRequired permissions section:

Required permissions

The following permissions are required to change subscription types and manage them:

  • Pull from a subscription:pubsub.subscriptions.consume
  • Create a subscription:pubsub.subscriptions.create
  • Delete a subscription:pubsub.subscriptions.delete
  • Get a subscription:pubsub.subscriptions.get
  • List a subscription:pubsub.subscriptions.list
  • Update a subscription:pubsub.subscriptions.update
  • Attach a subscription to a topic:pubsub.topics.attachSubscription
  • Get the IAM policy for a subscription:pubsub.subscriptions.getIamPolicy
  • Configure theIAM policy for a subscription:pubsub.subscriptions.setIamPolicy

You might also be able to get these permissions withcustom roles or otherpredefined roles.

You can configure access control at the project level and at the individualresource level. You can create a subscription in one project andattach it to a topic located in a different project.Ensure that you have the required permissions foreach project.

Modify delivery methods

You can switch between different subscription types.

Console

To modify a subscription, complete the following steps.

  1. In the Google Cloud console, go to theSubscriptions page.

    Go to Subscriptions

  2. Click next to the subscription to update.
  3. In theDelivery type, choose a delivery option.
  4. Fill in other subscription properties as required.
  5. ClickUpdate.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, aCloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. To modify the push endpoint URL, run thegcloud pubsub subscriptions modify-push-config command:

    gcloudpubsubsubscriptionsmodify-push-configSUBSCRIPTION_ID\--push-endpoint=PUSH_ENDPOINT

    If the subscription is already using pull delivery, setting the push endpoint switches the delivery method to push delivery.

    You can switch from push to pull delivery by changing the push endpoint to an empty string.

REST

To modify the push configurations of a subscription, use theprojects.subscriptions.modifyPushConfigmethod:

Request:

The request must be authenticated with an access token in theAuthorization header. To obtain an access token for the current Application Default Credentials:gcloud auth application-default print-access-token.

POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID:modifyPushConfigAuthorization: BearerACCESS_TOKEN

Request body:

{"pushConfig": {  "pushEndpoint": "PUSH_ENDPOINT"}}

Where:

  • PROJECT_ID is your project ID.
  • SUBSCRIPTION_ID is your subscription ID.
  • PUSH_ENDPOINT is a modified URL to you want to apply as your new push endpoint. For example,https://myproject.appspot.com/myhandler.
  • Response:

    If the request is successful, the response is an empty JSON object.

    C++

    Before trying this sample, follow the C++ setup instructions inQuickstart: Using Client Libraries. For more information, see thePub/Sub C++ API reference documentation.

    namespacepubsub_admin=::google::cloud::pubsub_admin;namespacepubsub=::google::cloud::pubsub;[](pubsub_admin::SubscriptionAdminClientclient,std::stringconst&project_id,std::stringconst&subscription_id,std::stringconst&endpoint){google::pubsub::v1::ModifyPushConfigRequestrequest;request.set_subscription(pubsub::Subscription(project_id,subscription_id).FullName());request.mutable_push_config()->set_push_endpoint(endpoint);autostatus=client.ModifyPushConfig(request);if(!status.ok())throwstd::runtime_error(status.message());std::cout <<"The subscription push configuration was successfully"            <<" modified\n";}

    C#

    Before trying this sample, follow the C# setup instructions inQuickstart: Using Client Libraries. For more information, see thePub/Sub C# API reference documentation.

    usingGoogle.Cloud.PubSub.V1;publicclassUpdatePushConfigurationSample{publicvoidUpdatePushConfiguration(stringprojectId,stringsubscriptionId,stringpushEndpoint){SubscriberServiceApiClientsubscriber=SubscriberServiceApiClient.Create();SubscriptionNamesubscriptionName=SubscriptionName.FromProjectSubscription(projectId,subscriptionId);PushConfigpushConfig=newPushConfig{PushEndpoint=pushEndpoint};subscriber.ModifyPushConfig(subscriptionName,pushConfig);}}

    Go

    The following sample uses the major version of the Go Pub/Sub client library (v2). If you are still using the v1 library, seethe migration guide to v2.To see a list of v1 code samples, seethe deprecated code samples.

    Before trying this sample, follow the Go setup instructions inQuickstart: Using Client Libraries.For more information, see thePub/Sub Go API reference documentation.

    import("context""fmt""io""cloud.google.com/go/pubsub/v2""cloud.google.com/go/pubsub/v2/apiv1/pubsubpb""google.golang.org/protobuf/types/known/fieldmaskpb")funcupdateEndpoint(wio.Writer,projectID,subscriptionName,endpointstring)error{// projectID := "my-project-id"// subscriptionName := "projects/my-project/subscriptions/my-sub"// endpoint := "https://my-test-project.appspot.com/push"ctx:=context.Background()client,err:=pubsub.NewClient(ctx,projectID)iferr!=nil{returnfmt.Errorf("pubsub.NewClient: %w",err)}deferclient.Close()req:=&pubsubpb.UpdateSubscriptionRequest{Subscription:&pubsubpb.Subscription{Name:subscriptionName,PushConfig:&pubsubpb.PushConfig{PushEndpoint:endpoint,},},UpdateMask:&fieldmaskpb.FieldMask{Paths:[]string{"push_config"},},}subConfig,err:=client.SubscriptionAdminClient.UpdateSubscription(ctx,req)iferr!=nil{returnfmt.Errorf("Update: %w",err)}fmt.Fprintf(w,"Updated subscription config: %v\n",subConfig)returnnil}

    Java

    Before trying this sample, follow the Java setup instructions inQuickstart: Using Client Libraries. For more information, see thePub/Sub Java API reference documentation.

    importcom.google.cloud.pubsub.v1.SubscriptionAdminClient;importcom.google.pubsub.v1.PushConfig;importcom.google.pubsub.v1.Subscription;importcom.google.pubsub.v1.SubscriptionName;importjava.io.IOException;publicclassUpdatePushConfigurationExample{publicstaticvoidmain(String...args)throwsException{// TODO(developer): Replace these variables before running the sample.StringprojectId="your-project-id";StringsubscriptionId="your-subscription-id";StringpushEndpoint="https://my-test-project.appspot.com/push";updatePushConfigurationExample(projectId,subscriptionId,pushEndpoint);}publicstaticvoidupdatePushConfigurationExample(StringprojectId,StringsubscriptionId,StringpushEndpoint)throwsIOException{try(SubscriptionAdminClientsubscriptionAdminClient=SubscriptionAdminClient.create()){SubscriptionNamesubscriptionName=SubscriptionName.of(projectId,subscriptionId);PushConfigpushConfig=PushConfig.newBuilder().setPushEndpoint(pushEndpoint).build();subscriptionAdminClient.modifyPushConfig(subscriptionName,pushConfig);Subscriptionsubscription=subscriptionAdminClient.getSubscription(subscriptionName);System.out.println("Updated push endpoint to: "+subscription.getPushConfig().getPushEndpoint());}}}

    Node.js

    Before trying this sample, follow the Node.js setup instructions inQuickstart: Using Client Libraries. For more information, see thePub/Sub Node.js API reference documentation.

    /** * TODO(developer): Uncomment these variables before running the sample. */// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';// Imports the Google Cloud client libraryconst{PubSub}=require('@google-cloud/pubsub');// Creates a client; cache this for further useconstpubSubClient=newPubSub();asyncfunctionmodifyPushConfig(topicNameOrId,subscriptionNameOrId){constoptions={// Set to an HTTPS endpoint of your choice. If necessary, register// (authorize) the domain on which the server is hosted.pushEndpoint:`https://${pubSubClient.projectId}.appspot.com/push`,};awaitpubSubClient.topic(topicNameOrId).subscription(subscriptionNameOrId).modifyPushConfig(options);console.log(`Modifiedpushconfigforsubscription${subscriptionNameOrId}.`);}

    Node.ts

    Before trying this sample, follow the Node.js setup instructions inQuickstart: Using Client Libraries. For more information, see thePub/Sub Node.js API reference documentation.

    /***TODO(developer):Uncommentthesevariablesbeforerunningthesample.*///consttopicNameOrId='YOUR_TOPIC_NAME_OR_ID';//constsubscriptionNameOrId='YOUR_SUBSCRIPTION_NAME_OR_ID';//ImportstheGoogleCloudclientlibraryimport{PubSub,CreateSubscriptionOptions}from'@google-cloud/pubsub';//Createsaclient;cachethisforfurtheruseconstpubSubClient=newPubSub();asyncfunctionmodifyPushConfig(topicNameOrId:string,subscriptionNameOrId:string,){constoptions:CreateSubscriptionOptions={//SettoanHTTPSendpointofyourchoice.Ifnecessary,register//(authorize)thedomainonwhichtheserverishosted.pushEndpoint:`https://${pubSubClient.projectId}.appspot.com/push`,};awaitpubSubClient.topic(topicNameOrId).subscription(subscriptionNameOrId).modifyPushConfig(options);console.log(`Modifiedpushconfigforsubscription${subscriptionNameOrId}.`);}

    Python

    Before trying this sample, follow the Python setup instructions inQuickstart: Using Client Libraries. For more information, see thePub/Sub Python API reference documentation.

    fromgoogle.cloudimportpubsub_v1# TODO(developer)# project_id = "your-project-id"# topic_id = "your-topic-id"# subscription_id = "your-subscription-id"# endpoint = "https://my-test-project.appspot.com/push"subscriber=pubsub_v1.SubscriberClient()subscription_path=subscriber.subscription_path(project_id,subscription_id)push_config=pubsub_v1.types.PushConfig(push_endpoint=endpoint)subscription=pubsub_v1.types.Subscription(name=subscription_path,topic=topic_id,push_config=push_config)update_mask={"paths":{"push_config"}}# Wrap the subscriber in a 'with' block to automatically call close() to# close the underlying gRPC channel when done.withsubscriber:result=subscriber.update_subscription(request={"subscription":subscription,"update_mask":update_mask})print(f"Subscription updated:{subscription_path}")print(f"New endpoint for subscription is:{result.push_config}.")

    Ruby

    The following sample uses Ruby Pub/Sub client library v3. If you are still using the v2 library, see the migration guide to v3.To see a list of Ruby v2 code samples, seethe deprecated code samples.

    Before trying this sample, follow the Ruby setup instructions inQuickstart: Using Client Libraries.For more information, see thePub/Sub Ruby API reference documentation.

    # subscription_id   = "your-subscription-id"# new_endpoint      = "Endpoint where your app receives messages""pubsub=Google::Cloud::PubSub.newsubscription_admin=pubsub.subscription_adminsubscription=subscription_admin.get_subscription\subscription:pubsub.subscription_path(subscription_id)subscription.push_config=Google::Cloud::PubSub::V1::PushConfig.new\push_endpoint:new_endpointsubscription_admin.update_subscriptionsubscription:subscription,update_mask:{paths:["push_config"]}puts"Push endpoint updated."

    Note: Switching from a push to a pull subscription takes several minutes tocomplete. In this interval, pull requests might generate errors and pushrequests might continue.

    What's next

    Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

    Last updated 2026-02-19 UTC.