Learn how to use the RetrieveMerchantSettings, UpdateMerchantSettings, RetrieveLocationSettings, and RetrieveLocationSettings 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.
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.
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.
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:
{
"merchant_settings": {
"merchant_id": "MERCHANT_ID",
"updated_at": "2022-06-16T22:25:35Z",
"payment_methods": {
"apple_pay": {
"enabled": false
},
"google_pay": {
"enabled": true
},
"cash_app_pay": {
"enabled": true
},
"afterpay_clearpay": {
"enabled": true,
"order_eligibility_range": {
"min": {
"amount": 100,
"currency": "USD",
},
"max": {
"amount": 10000,
"currency": "USD",
},
},
"item_eligibility_range": {
"min": {
"amount": 100,
"currency": "USD",
},
"max": {
"amount": 10000,
"currency": "USD",
},
},
}
}
}
}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:
{
"merchant_settings": {
"merchant_id": "MERCHANT_ID",
"updated_at": "2022-06-16T22:25:35Z",
"payment_methods": {
"apple_pay": {
"enabled": false
},
"google_pay": {
"enabled": true
},
"cash_app_pay": {
"enabled": true
},
"afterpay_clearpay": {
"enabled": true,
"order_eligibility_range": {
"min": {
"amount": 100,
"currency": "USD",
},
"max": {
"amount": 10000,
"currency": "USD",
},
},
"item_eligibility_range": {
"min": {
"amount": 100,
"currency": "USD",
},
"max": {
"amount": 10000,
"currency": "USD",
},
},
}
}
}
}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:
{
"location_settings": {
"location_id": "LOCATION_ID_1",
"updated_at": "2022-06-16T22:25:35Z",
"customer_notes_enabled": false,
"policies": [
{
"uid": "POLICY_ID_1",
"title": "Return Policy",
"description": "This is my Return Policy",
},
],
"branding": {
"header_type": "FRAMED_LOGO",
"button_color": "#ffffff",
"button_shape": "ROUNDED",
},
"tipping": {
"percentages": [10, 15, 20],
"smart_tipping_enabled": true,
"default_percent": 15,
"default_whole_amount_money": {
"amount": 100,
"currency": "USD",
},
"whole_amounts": [
{
"amount": 1000,
"currency": "USD",
},
{
"amount": 1500,
"currency": "USD",
},
{
"amount": 2000,
"currency": "USD",
},
],
},
}
}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:
{
"location_settings": {
"location_id": "LOCATION_ID_1",
"updated_at": "2022-06-16T22:25:35Z",
"customer_notes_enabled": false,
"policies": [
{
"uid": "POLICY_ID_1",
"title": "Return Policy",
"description": "This is my Return Policy",
},
],
"branding": {
"header_type": "FRAMED_LOGO",
"button_color": "#ffffff",
"button_shape": "ROUNDED",
},
"tipping": {
"percentages": [10, 15, 20],
"smart_tipping_enabled": true,
"default_percent": 15,
"default_whole_amount_money":
{
"amount": 100,
"currency": "USD",
},
"whole_amounts": [
{
"amount": 1000,
"currency": "USD",
},
{
"amount": 1500,
"currency": "USD",
},
{
"amount": 2000,
"currency": "USD",
},
],
},
}
}The following limitations apply to the settings endpoints of the Checkout API:
- 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.