Configure Preset Charges for Quick Payments Beta release

This is pre-release documentation for an API in public beta and is subject to change.

You can configure up to three preset charges with the quick amounts settings. Using configured quick amounts settings, the Square Register displays the preset charges in the Quick Amounts dialog box 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 does not 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:

curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "object": {
      "type": "QUICK_AMOUNTS_SETTINGS",
      "is_deleted": false,
      "present_at_all_locations": false,
      "present_at_location_ids": [
        "{{LOCATION_ID}}"
      ],
      "quick_amounts_settings_data": {
        "option": "MANUAL",
        "amounts": [
          {
            "amount": {
              "amount": 855,
              "currency": "USD"
            },
            "type": "QUICK_AMOUNT_TYPE_MANUAL",
            "ordinal": 1,
            "score": 100
          },
          {
            "amount": {
              "amount": 85,
              "currency": "USD"
            },
            "type": "QUICK_AMOUNT_TYPE_MANUAL",
            "ordinal": 2,
            "score": 100
          }
        ]
      },
      "id": "#quick_amount_1"
    },
    "idempotency_key": "{{YOUR_ITEMPOTENCY_VALUE}}"
  }'

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"
        }
      ]
    }

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:

curl https://connect.squareupsandbox.com/v2/catalog/search \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "include_deleted_objects": false,
    "include_related_objects": true,
    "object_types": [
      "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"
}

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.

curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "blart445",
    "object": {
      "id": "CP4I57JIFFVMRSZU63WPH6UD",
      "type": "QUICK_AMOUNTS_SETTINGS",
      "present_at_location_ids": [
        "{{LOCATION_ID}}"
      ],
      "present_at_all_locations": false,
      "quick_amounts_settings_data": {
        "option": "MANUAL",
        "eligible_for_auto_amounts": false,
        "amounts": [
          {
            "amount": {
              "amount": 1500,
              "currency": "USD"
            },
            "type": "QUICK_AMOUNT_TYPE_MANUAL",
            "ordinal": 1,
            "score": 100
          }
        ]
      },
      "version": 1587157099397
    }
  }'

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.

curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "blart_blart4",
    "object": {
      "id": "CP4I57JIFFVMRSZU63WPH6UD",
      "type": "QUICK_AMOUNTS_SETTINGS",
      "present_at_location_ids": [
        "{{LOCATION_ID}}"
      ],
      "quick_amounts_settings_data": {
        "option": "DISABLED",
        "eligible_for_auto_amounts": true
      },
      "is_deleted": false,
      "present_at_all_locations": false,
      "version": 1587157099397
    }
  }'

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
    }
  }
}