Manage checkout settings

The checkout feature speeds up purchasing for customers ready to buy by letting them go directly from Google product listings to your website's cart or checkout page, which can improve conversion rates and smooth the shopping experience.

With Merchant API, you can manage the settings for this feature using the CheckoutSettings resource.

This guide explains how to use Merchant API to create and manage your enrollment in the checkout feature programmatically.

For more information, see Add a checkout link for your products.

Prerequisites

To use the CheckoutSettings resource and associated methods, make sure to do the following:

  • You must be approved for and participating in Shopping Ads, free listings, or both.
  • Your sales country must be the United States.

Methods

To create, retrieve, update, and delete checkout settings, you can use the following methods:

Create checkout settings

To create a checkout setting, use the checkoutSettings.create method. Include the uri_settings with either checkout_uri_template or cart_uri_template and the selected eligible_destinations in the request body.

Here's a sample request:

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/checkout/checkoutSettings

{
  "uri_settings": {
    "checkout_uri_template": "https://www.your-store.com/checkout?item_id={id}"
  },
  "eligible_destinations": [
    "FREE_LISTINGS",
    "SHOPPING_ADS"
  ]
}

Replace {ACCOUNT_ID} with the unique identifier of your Merchant Center account.

Here's a sample response from a successful call:

{
  "name": "accounts/{ACCOUNT_ID}/programs/checkout/checkoutSettings",
  "uri_settings": {
    "checkout_uri_template": "https://www.your-store.com/checkout?item_id={id}"
  },
  "eligible_destinations": [
    "FREE_LISTINGS",
    "SHOPPING_ADS"
  ],
  "enrollment_state": "ENROLLED",
  "review_state": "IN_REVIEW",
  "effective_uri_settings": {
    "checkout_uri_template": "https://www.your-store.com/checkout?item_id={id}"
  },
  "effective_enrollment_state": "ENROLLED",
  "effective_review_state": "IN_REVIEW"
}

Retrieve checkout settings

To retrieve your checkout settings, including the URL template, selected destinations, enrollment status, and URL review status, use the checkoutSettings.get method.

Here's a sample request:

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/checkout/checkoutSettings

Here's a sample response from a successful call:

{
  "name": "accounts/{ACCOUNT_ID}/programs/checkout/checkoutSettings",
  "uri_settings": {
    "checkout_uri_template": "https://www.your-store.com/checkout?item_id={id}"
  },
  "eligible_destinations": [
    "FREE_LISTINGS",
    "SHOPPING_ADS"
  ],
  "enrollment_state": "ENROLLED",
  "review_state": "APPROVED",
  "effective_uri_settings": {
    "checkout_uri_template": "https://www.your-store.com/checkout?item_id={id}"
  },
  "effective_enrollment_state": "ENROLLED",
  "effective_review_state": "APPROVED"
}

Update checkout settings

To update your checkout settings, use the checkoutSettings.update method. Include the fields you want to change in the request body and specify those fields in the update_mask query parameter.

update_mask supports the following fields:

  • eligible_destinations
  • uri_settings

Here's a sample request updating the URL and removing the ads destination:

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/checkout/checkoutSettings?update_mask=uri_settings,eligible_destinations

{
  "uri_settings": {
    "cart_uri_template": "https://shop.your-store.com/add_to_cart?sku={id}"
  },
  "eligible_destinations": [
    "FREE_LISTINGS"
  ]
}

Here's a sample response from a successful call:

{
  "name": "accounts/{ACCOUNT_ID}/programs/checkout/checkoutSettings",
  "uri_settings": {
    "cart_uri_template": "https://shop.your-store.com/add_to_cart?sku={id}"
  },
  "eligible_destinations": [
    "FREE_LISTINGS"
  ],
  "enrollment_state": "ENROLLED",
  "review_state": "IN_REVIEW", // Review state will always be set to "IN_REVIEW" after URL update
  "effective_uri_settings": {
    "cart_uri_template": "https://shop.your-store.com/add_to_cart?sku={id}"
  },
  "effective_enrollment_state": "ENROLLED",
  "effective_review_state": "IN_REVIEW"
}

Delete

To delete the checkout settings, use the checkoutSettings.delete method.

This action removes your account-level configuration, un-enrolls you from the checkout program, and stops checkout links from appearing on your products in free listings and Shopping ads.

Here's a sample request:

DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/checkout/checkoutSettings

A successful call returns an empty response body.

You have two ways to provide checkout URLs for your products:

  • Account-level (sub-API or Merchant Center): To define a single URL template, either checkout_uri_template or cart_uri_template, you can use the sub-API or Merchant Center settings. This template is applied to all your eligible products. We recommend that you have a consistent URL across your products. For example, yourstore.com/checkout?id={id}.

  • Product-level (Feed): To provide a specific checkout URL for individual products, use the checkout_link_template attribute in your product feed. This allows for customized URLs per product or lets you offer checkout only for a subset of your inventory.

  • If you set an account-level URL template using this sub-API, make sure that you don't submit values for the checkout_link_template attribute in your feed for those products.

  • If you use the checkout_link_template feed attribute, make sure that you don't set an account-level URL template using the sub-API or Merchant Center settings. You can still use the sub-API to select the eligible_destinations without providing uri_settings if you're managing URLs solely through the feed.

Checkout URL template

The checkout URL template lets you include a checkout URL in your product data which gives online shoppers the option to go directly to your checkout page from your listings. It must contain {ID} parameter placeholder and have a matching domain.

When you set up checkout links using the sub-API, use the uri_settings field. This field accepts one of two templates:

  • checkout_uri_template: A URL template that, when the placeholder is filled, directs the user to your checkout page with the specific item ready for purchase.
  • cart_uri_template: A URL template that directs the user to your shopping cart page with the specific item added to the cart.

Example templates

  • Checkout: https://www.your-store.com/checkout?item_id={id}
  • Cart: https://shop.your-store.com/add_to_cart?product_sku={id}

Make sure to meet the following requirements:

  • Your URL template must point to a valid page on your site that matches your registered domain, works using the HTTP GET method, and doesn't require the customer to sign in.
  • The domain from the provided checkout template must match the product domain.

Learn more