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.

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.

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.

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:

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:

    {
      "catalog_object": {
        "type": "QUICK_AMOUNTS_SETTINGS",
        "id": "IXEVKMKA6CWG6CH4MFB32YPV",
        "updated_at": "2020-04-17T20:50:44.31Z",
        "version": 1587156644310,
        "is_deleted": false,
        "present_at_all_locations": false,
        "present_at_location_ids": [
          "{{LOCATION_ID}}"
        ],
        "quick_amounts_settings_data": {
          "option": "MANUAL",
          "eligible_for_auto_amounts": false,
          "amounts": [
            {
              "type": "QUICK_AMOUNT_TYPE_MANUAL",
              "amount": {
                "amount": 855,
                "currency": "USD"
              },
              "score": 100,
              "ordinal": 1
            },
            {
              "type": "QUICK_AMOUNT_TYPE_MANUAL",
              "amount": {
                "amount": 85,
                "currency": "USD"
              },
              "score": 100,
              "ordinal": 1
            }				
          ]
        }
      },
      "id_mappings": [
        {
          "client_object_id": "#quick_amount_1",
          "object_id": "IXEVKMKA6CWG6CH4MFB32YPV"
        }
      ]
    }

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:

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

{
  "objects": [
    {
      "type": "QUICK_AMOUNTS_SETTINGS",
      "id": "CP4I57JIFFVMRSZU63WPH6UD",
      "updated_at": "2020-04-17T20:58:19.397Z",
      "version": 1587157099397,
      "is_deleted": false,
      "present_at_all_locations": false,
      "present_at_location_ids": [
        "{{LOCATION_ID}}"
      ],
      "quick_amounts_settings_data": {
        "option": "MANUAL",
        "eligible_for_auto_amounts": true,
        "amounts": [
          {
            "type": "QUICK_AMOUNT_TYPE_MANUAL",
            "amount": {
              "amount": 855,
              "currency": "USD"
            },
            "score": 100,
            "ordinal": 1
          },
          {
            "type": "QUICK_AMOUNT_TYPE_MANUAL",
            "amount": {
              "amount": 85,
              "currency": "USD"
            },
            "score": 100,
            "ordinal": 1
          }				
        ]
      }
    }
  ],
  "latest_time": "2020-04-17T22:37:22.213Z"
}

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.

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

The response returns the following:

{
  "catalog_object": {
    "type": "QUICK_AMOUNTS_SETTINGS",
    "id": "CP4I57JIFFVMRSZU63WPH6UD",
    "updated_at": "2020-04-17T22:37:22.213Z",
    "version": 1587163042213,
    "is_deleted": false,
    "present_at_all_locations": false,
    "present_at_location_ids": [
      "{{LOCATION_ID}}"
    ],
    "quick_amounts_settings_data": {
      "option": "DISABLED",
      "eligible_for_auto_amounts": false
    }
  }
}