Checkout Settings

Applies to: Checkout API

Learn how to access and modify checkout settings for payment links.

Link to section

Overview

Use the RetrieveMerchantSettings, UpdateMerchantSettings, RetrieveLocationSettings, and UpdateLocationSettings endpoints to access and modify checkout settings for payment links created using the Checkout API.

Using these Checkout API endpoints, you can adjust seller-level and location-level controls without requiring sellers to manually log in to the Seller Dashboard.

Link to section

Requirements and limitations

  • The Square Sandbox isn't supported.
  • Enabling and disabling Afterpay or Clearpay as a payment method isn't supported. Sellers need to enable or disable Afterpay or Clearpay in the Seller Dashboard.
  • Custom attribute settings cannot be updated.
Link to section

Example use case

Consider a scenario of a home repair contractor. You might use the settings endpoints of the Checkout API to:

  • Configure tipping options with custom presets and a default tip during checkout.
  • Enable specific payment methods, including Apple Pay, Google Pay, or Cash App Pay.
  • Customize branding settings by defining the color and shape of the Buy button and updating your logo.
  • Update company or purchase policies and enable or disable customer notes.
Link to section

Resources

The settings endpoints provide the following resources:

  • Merchant Settings - You can retrieve and update payment method types scoped to a seller.
  • Location Settings - You can retrieve and update tipping, branding, policies, and customer-enabled note settings scoped to a location.

Both merchant and location settings have default settings; therefore, Square doesn't offer endpoints to create or delete settings.

Link to section

Retrieve Merchant Settings

The RetrieveMerchantSettings endpoint returns merchant settings based on the merchant ID. Square automatically gets the merchant ID from the authorization token. To call this endpoint, set MERCHANT_PROFILE_READ and PAYMENT_METHODS_READ for the OAuth scope.

The following example shows how to retrieve the available payment methods: Apple Pay, Google Pay, Cash App Pay, and Afterpay:

Retrieve merchant settings

The following is an example response:

Link to section

Update Merchant Settings

The UpdateMerchantSettings endpoint updates merchant settings based on the merchant ID. Square automatically gets the merchant ID from the authorization token. To call this endpoint, set MERCHANT_PROFILE_READ, MERCHANT_PROFILE_WRITE, and PAYMENT_METHODS_READ for the OAuth scope.

The following example shows how to update the payment method to Apple Pay:

Update merchant settings

The following is an example response:

Link to section

Retrieve Location Settings

The RetrieveLocationSettings endpoint returns location settings based on the location ID. You need to provide the location ID in the URL. To call this endpoint, set MERCHANT_PROFILE_READ for the OAuth scope.

The following example shows how to retrieve the location settings, including policies, branding, and tipping:

Retrieve location settings

The following is an example response:

Link to section

Update Location Settings

The UpdateLocationSettings endpoint updates location settings based on the location ID. You need to provide the location ID in the URL. To call this endpoint, set MERCHANT_PROFILE_READ and MERCHANT_PROFILE_WRITE for the OAuth scope.

The following example shows how to disable the customer notes setting and set policies, branding, and tipping:

Update location settings

The following is an example response: