Configure Preset Charges for Quick Payments

Applies to: Catalog API

Learn how to add up to three custom amounts to the Square Register Quick Amounts dialog.

Link to section

Overview

Using configured quick amounts settings, the Square Register displays the preset charges in the Quick Amounts dialog on the checkout screen. The quick amounts settings are seller and location dependent. You can call the Catalog API to configure quick amounts manually. Alternatively, Square can determine them automatically based on seller's order history at a location.

When a QUICK_AMOUNTS_SETTINGS catalog object is created for a location, the seller at that location sees a quick amount configuration screen on Square POS with the settings from the QUICK_AMOUNTS_SETTINGS object.

A screenshot showing the Quick Amounts configuration screen on Square Point of Sale.

In this example, the Square POS shows the two quick amounts set by the seller for the specific location. Unlike other catalog objects, a QUICK_AMOUNTS_SETTINGS object doesn't require items or item variations being added to the catalog item collection. The presence of a CatalogQuickAmountSettings object only configures and enables quick amount values.

Link to section

Create a quick amount setting

To create a QUICK_AMOUNTS_SETTINGS object, call the UpsertCatalogObject endpoint, specifying QUICK_AMOUNTS_SETTINGS as the object's type property and providing an appropriate CatalogQuickAmountsSettings object on the quick_amounts_settings_data property.

The following cURL command shows how to use the Catalog API to create a QuickAmountsSettings object:

Upsert catalog object

In the request body, the present_at_all_locations field must be set to false to indicate that the resulting quick amounts settings apply to the specified location ({{LOCATION_ID}}) as referenced in the present_at_locations_ids field. In this example, the option field of quick_amounts_settings_data is set to MANUAL. This option lets the seller choose manually created quick amounts as specified herein. You can set option to AUTO to let the seller to choose automatically created quick amounts based on the seller's payment-receiving trends.

When successfully created, a CatalogQuickAmountsSettings object similar to the following is returned:

Note

A location can have only one QUICK_AMOUNTS_SETTINGS object configured for it. If you attempt to create a second object of this type, you get an error.

Link to section

Get an existing quick amount setting

To obtain any of the existing QUICK_AMOUNTS_SETTINGS objects for a seller's location, call the SearchCatalogObjects endpoint, specifying QUICK_AMOUNTS_SETTINGS in the object_types list.

The following cURL command shows the API request to retrieve non-deleted quick amounts settings:

Search catalog objects

The response returns an array of non-deleted QUICK_AMOUNTS_SETTINGS objects, one per location, as shown:

Link to section

Update a quick amount setting

To update an existing QUICK_AMOUNTS_SETTINGS object, call the UpsertCatalogObject specifying an CatalogQuickAmountsSettings object whose id field is set to the ID of the existing object and whose quick_amounts_settings_data field contains the updated settings.

Set the id field to the object_id value in the previous response. Set the version to the version returned in the previous response.

Upsert catalog object

Link to section

Disable quick amounts

To disable preset quick amounts, call the UpsertCatalogObject endpoint and specify the option field of the quick_amounts_settings_data object to DISABLE.

Upsert catalog object

The response returns the following: